diff --git a/.claude/skills/update-changelog/SKILL.md b/.claude/skills/update-changelog/SKILL.md index 5ee83d92..f6eff851 100644 --- a/.claude/skills/update-changelog/SKILL.md +++ b/.claude/skills/update-changelog/SKILL.md @@ -114,6 +114,50 @@ If a doc page **doesn't yet exist** for the feature, do NOT auto-create one — **Never write a `[Docs](...)` link without verifying the file exists.** Broken links erode trust in the changelog. +### 4a. Extract factual assertions + +Before writing any prose, write down the discrete facts the release establishes. Save to +`prisma-airs/_project/releases/@.yaml`. + +This is the input to the KB contribution step (added once KB MCP access exists — see +`prisma-airs/_project/README.md`, "Changelog contribution path"). Until then it stands on its own as +a review artifact: it makes the release's factual content inspectable separately from how it +was worded. + +```yaml +release: + id: "gateway-enterprise-node@v2.21.0" + repo: "Portkey-AI/gateway-enterprise-node" + date: "2026-08-14" + source_revision: "" +assertions: + - id: r1 + text: "" + kind: new-capability # new-capability|behavior-change|default-change|fix|deprecation + applies_to: "" + supersedes: [] # existing facts this invalidates; [] if net-new + affects: [] # doc routes carrying the superseded fact +``` + +Rules: + +- **One assertion per fact, not per PR.** A PR can establish several facts, and several PRs + can establish one. Bucket by fact. +- **State the fact, not the change to the docs.** ✅ `"Default request timeout is 60s"` — + ❌ `"Updated the timeout section"`. +- **`supersedes` is the field that matters.** A release that changes a default doesn't only + add a fact, it invalidates one. That invalidation is what identifies stale pages. Populate + it by searching for the current documented value: + ```bash + grep -rn "" product/ api-reference/ self-hosting/ + ``` + Put whatever routes that finds into `affects`. +- **`kind: fix` assertions usually have empty `supersedes`** — a bug fix restores documented + behavior rather than changing it. If a fix *does* change documented behavior, it is a + `behavior-change`, not a fix. +- **Skip non-facts.** Dependency bumps, CI changes, and internal refactors produce no + assertions even when they produce changelog lines. + ### 5. Write the changelog entry Insert a new `` block immediately after the frontmatter, **above** the previous top entry. Pattern: @@ -162,17 +206,41 @@ In the frontmatter, update: sidebarTitle: " []" ``` -### 7. Apply documentation updates flagged in step 4 +### 7. Apply documentation updates flagged in step 4 — as a separate change + +A release produces **two outputs on two different clocks.** Do not merge them into one commit. -For approved doc updates: -- Make the smallest possible edit — one new section, one new table row -- Cross-link from the changelog entry to the updated doc +| Output | Mutability | Ships when | +|---|---|---| +| The `` changelog entry | **Immutable once published.** Corrections append a new entry; they never rewrite the old one. | With the release | +| Patches to guides / reference / API pages | Mutable — normal doc content | Once the facts are confirmed | + +The reason: the changelog entry is a dated observation of what shipped. It stays true forever, +even after the behavior it describes changes again. A guide states current behavior, so it +has to keep changing. Rewriting a historical release entry to match the current guide destroys +the record of what a customer running that version actually got. + +So: + +- **Separate commits.** Changelog entry first, guide patches second. Separate PRs if the + guide patches are large or need a different reviewer. +- Make the smallest possible edit to each guide — one new section, one new table row. +- Cross-link from the changelog entry to the updated doc. +- If a guide patch turns out to be wrong, fix the guide. **Never** edit the shipped + `` block to match. +- Drive the patch list from `affects` in the step 4a assertion file, not from memory. + +Once KB MCP access exists, step 4b (submit assertions to the KB) slots in here, and the guide +patches additionally wait on KB acceptance while the changelog entry does not. See +`prisma-airs/_project/README.md` under "Changelog contribution path". ### 8. Report back End with a summary: - Version added and the changelog file path -- Any docs updated (with file paths) +- The assertion file path, and the assertion count broken down by `kind` +- Any assertions with a non-empty `supersedes` — these are the facts that made existing docs stale, and they are the ones most likely to be missed +- Any docs updated (with file paths), noted as a **separate change** from the changelog entry - Any **flagged** docs that the user should consider creating (new providers, new guardrails, new endpoints) — these are typically larger tasks involving `docs.json` ## Tips @@ -204,3 +272,12 @@ End with a summary: ❌ Don't include every PR — chore/CI/refactor PRs without user impact belong on the cutting room floor ✅ Skip ruthlessly; the changelog is for users, not contributors + +❌ Don't edit a previously published `` block to reflect current behavior +✅ Historical entries are immutable. A later release changed things — say so in the later entry. The old entry stays true for the version it describes + +❌ Don't ship the changelog entry and the guide patches as one commit +✅ Two outputs, two clocks (see step 7). The entry is a dated record; the guides state current behavior + +❌ Don't write assertions that describe the documentation ("updated the timeout section") +✅ Write the fact itself ("default request timeout is 60s") — assertions are product facts, not edit logs diff --git a/.mintignore b/.mintignore new file mode 100644 index 00000000..ad138ac2 --- /dev/null +++ b/.mintignore @@ -0,0 +1,12 @@ +# Files Mintlify should not process. +# +# Mintlify parses .md as well as .mdx, and omitting a file from docs.json +# navigation does NOT exclude it from the build or from the public exports +# (llms.txt / llms-full.txt). This file is the mechanism that does. +# +# Syntax is gitignore-style. Mintlify additionally always ignores .git, +# .github, .claude, .agents, .idea, node_modules, and README.md. + +# Planning and control artifacts for the Prisma AIRS docs project. +# Working documents, not pages. See prisma-airs/_project/README.md. +prisma-airs/_project/ diff --git a/docs.json b/docs.json index db863ff0..77be1c87 100644 --- a/docs.json +++ b/docs.json @@ -318,7 +318,6 @@ }, "self-hosting/cache-behavior", "self-hosting/prometheus-metrics", - "self-hosting/fips-compliant-images", { "group": "Air-Gapped Deployments (Legacy)", @@ -1456,6 +1455,22 @@ } ] }, + { + "version": "Prisma AIRS", + "tabs": [ + { + "tab": "Docs", + "groups": [ + { + "group": "Introduction", + "pages": [ + "prisma-airs/overview" + ] + } + ] + } + ] + }, { "version": "Virtual Keys (Deprecated)", "tabs": [ diff --git a/prisma-airs/_project/README.md b/prisma-airs/_project/README.md new file mode 100644 index 00000000..b153b836 --- /dev/null +++ b/prisma-airs/_project/README.md @@ -0,0 +1,663 @@ +# Prisma AIRS AI Gateway — docs project + +The canonical working document for the initiative described in +[`prisma-airs-docs-mintlify-handoff-v2.md`](./prisma-airs-docs-mintlify-handoff-v2.md). +Everything not published lives here. One file, so facts are stated once. + +Companion: [`openapi-handoff.md`](./openapi-handoff.md) — kept separate only because it is +handed to a different agent building a different repository. + +Last updated 2026-09-07. + +--- + +## Status + +**Page authoring is blocked.** No authenticated Prisma AIRS KB access exists from this +workspace, and §3 rule 2 forbids publishing substantive assertions without accepted KB support. + +§6 permits what has been done instead: "Proceed with page contracts, editorial standards, and +local structure while access is pending. Do not claim integrated success until a real +authorized read/contribution/publication round trip is demonstrated." **No such round trip has +been demonstrated.** + +Shipped so far: this document, the OpenAPI handoff, a `.mintignore`, a "Prisma AIRS" navigation +version in `docs.json`, `prisma-airs/overview.mdx` as a scaffold carrying **no product +capability claims**, and release-assertion extraction in +`.claude/skills/update-changelog/SKILL.md`. + +--- + +## Ground rules + +The constraints everything else derives from. Each is stated here and not repeated. + +**Grounding.** Every substantive published assertion — numbers, defaults, limits, instructions, +prerequisites, code assumptions, claimed outputs — needs accepted KB support. Headings, +connective prose and editorial framing do not. No invented content fills a gap (rule 5). + +**Rule 7.** Published documentation is never corroboration of its own claims. This is the most +important line in the brief. It is why the reconciliation loop is a divergence detector rather +than an autonomous writer, and why the existing corpus is not evidence of anything. + +**Re-ground, do not inherit.** Prisma AIRS pages are produced from KB claims, not by rebranding +existing prose. Consequence: **defects in the Portkey-branded corpus are out of scope +entirely** — not deferred, not backlogged. 66 broken links, unverifiable compliance and uptime +claims, possibly-wrong SSO/SCIM pages: none are inherited, so none need fixing. Do not open +triage against them. Standing instruction: **do not modify non-Prisma-AIRS docs at all.** + +**Build exclusion.** Navigation omission provides *zero* exclusion — Mintlify parses `.md` as +well as `.mdx`, and an unreferenced path is still a built path that reaches `llms.txt` and +`llms-full.txt`. The only mechanism is the repo-root `.mintignore`, which excludes +`prisma-airs/_project/`. Anything added here inherits it; anything added elsewhere does not. +This was learned the hard way — see [Feedback for the brief](#feedback-for-the-brief). + +**Two trusted sources.** The KB is primary. The OpenAPI specification is a second trusted +source outside the KB corpus, under a scoped recorded exemption to rule 1. Details under +[Decisions](#decisions). + +--- + +## Decisions + +| # | Decision | Date | +|---|---|---| +| Q1 | **Scope:** the whole corpus is Prisma AIRS AI Gateway, rebranded in place. Other tabs are modules of it, not separate products. | 2026-09-07 | +| Q2 | **KB endpoint:** still open. Parked at operator's call. **Blocks all page authoring.** | — | +| Q3 | **Naming rule:** approved as written below. | 2026-09-07 | +| Q4 | **Onboarding:** through Strata Cloud Manager. Documented detail waits for the KB — not an operator call, and not to be inferred from the existing `app.portkey.ai` quickstart. | 2026-09-07 | +| Q5 | **SSO/SCIM correctness:** moot. Portkey-corpus content, never inherited. | 2026-09-07 | +| Q6 | **OpenAPI:** a new repository is the source. The spec is a **second trusted source outside the KB corpus** — see below. | 2026-09-07 | +| Q7 | **Owners:** Vrushank Vyas holds factual review, editorial publication, conflicts, urgent withdrawal. | 2026-09-07 | +| Q8 | **Virtual Keys version:** keep as is, do not touch. | 2026-09-07 | +| Q9 | **Changelog publication:** release-only exception approved. Entries publish on the release schedule; guide and reference patches wait for KB acceptance. | 2026-09-07 | +| Q10 | **Loop infrastructure:** largely settled — see [Reconciliation loop](#reconciliation-loop). Two items of workflow config remain. | 2026-09-07 | +| Q11 | **Generated ancestry:** hard prerequisite. Ingestion must *refuse* generated-ancestry content as corroborating evidence. Verification rides with Q2. | 2026-09-07 | +| Q12 | **Environments:** managed and hybrid. **Product behaviour is deployment-invariant.** English only. | 2026-09-07 | +| Q13 | **Change discovery:** downgraded to a performance detail — reconcile against manifests regardless of contract shape. | 2026-09-07 | +| Q14 | **Navigation primitive:** Prisma AIRS stays a `navigation.versions[]` entry **for now**. Not `products`, `tabs` or `anchors`. Provisional by the operator's own wording — see below. | 2026-09-07 | + +**Launch scope and navigation skeleton are reserved to Vrushank**, who is hand-designing them, +reusing and improving the Portkey structure. Do not propose a navigation tree or page +inventory. + +**Deferred by agreement:** `mint a11y` and `mint test` adopted later. + +### The OpenAPI exemption (Q6) + +The specification is a key source of trusted knowledge sitting *outside* the KB corpus — +co-equal with the KB, not subordinate and not merely an ingestion input. + +This is a deliberate deviation from §3 rule 1's "sole factual authority," scoped to the API +specification, recorded rather than assumed precisely so it cannot be cited as precedent for a +second exemption. + +1. Two trusted sources, one truth. Neither silently overrides the other. +2. Conflicts are resolved by **maintainers** — never automatically, never last-write-wins. +3. Both stay in sync; **drift from either side is raised.** There is no authoritative side to + fall back on. +4. Sync is **bidirectional and webhook-driven**: a spec change notifies the KB, a KB change + notifies the spec repository. + +### Version, not product (Q14) + +Prisma AIRS is a third entry in `navigation.versions[]`, between "Latest" and "Virtual Keys +(Deprecated)". "Latest" stays first, so it stays the default. + +Decided **"at the moment"** — treat it as provisional, and record the cost so a later switch is +a decision rather than a discovery. + +- Readers see a version switcher, which frames Prisma AIRS as a variant of Portkey docs rather + than as the product. That framing is wrong on the merits and acceptable while the Prisma AIRS + page count is small. +- The switch is cheap while the corpus is small and gets steadily more expensive: moving to + `products` or `tabs` at the top level rewrites every route, which means redirects for every + published page and re-binding for anything the OpenAPI group config generates. +- So the **revisit trigger is route stability, not page count.** Reconsider before the first + substantial batch of Prisma AIRS pages publishes and acquires inbound links — not after. + +Nothing else in this document depends on the choice. Page contracts, provenance, the loop and +the spec handoff are all route-shaped, not primitive-shaped. + +### Deployment invariance (Q12) + +Managed and hybrid behave identically, so `applies_to` carries **version** applicability only. +No environment-variant page sets, no per-environment claim fan-out, one-dimensional coverage +ledger. Deployment is described plainly where it is genuinely the subject and nowhere else. +Do not reintroduce environment branching without a specific recorded reason — it multiplies the +claim space and every index downstream. + +--- + +## Open items + +- **Q2 — KB endpoint, identity, tool contract.** Needs the tool surface: claim reads, public + eligibility fields, change discovery, contribution submission, task status. Parked. +- **Q11 verification.** Ask for the field name and the code path where the confidence model + reads ancestry and declines the content. "We preserve the metadata" is a passing answer to + the wrong question. +- **Tier-3 default assignee** and the **self-reporting health check** — two lines of workflow + config, decided when the loop is built. +- **`tags[].name`** in the new spec: simultaneously display text and reference key. Flagged for + a human, not decided. +- **`x-mint.mcp` coverage** — which operations become agent-callable tools is a product surface + decision. + +The configured `mcp-gateway` MCP server times out on connect (`CONNECT_TIMEOUT`, 30s). Its name +matches Portkey's own MCP Gateway product, so it is probably not the KB — but confirm rather +than assume. If it *is* the KB path, that timeout is the highest-priority unblock. + +--- + +## Platform facts + +Verified in this workspace against `docs.json` and the installed `mint` CLI **4.2.876**. +mintlify.com is unreachable from here (WebSearch blocked by org policy, no WebFetch, curl +denied), so this is grounded in the repository and the CLI rather than in Mintlify's own +documentation. Re-check the finer points during implementation. + +| Capability | Status | Evidence | +|---|---|---| +| Navigation model | Verified | `navigation.versions[]` → tabs → groups → pages. A third version, "Prisma AIRS", now sits between "Latest" and "Virtual Keys (Deprecated)". "Latest" stays first, so it stays default. | +| Strict validation | Verified | `mint validate` exits non-zero on warnings | +| Build exclusion | Verified | repo-root `.mintignore`, gitignore syntax. Defaults also ignore `.git`, `.github`, `.claude`, `.agents`, `.idea`, `node_modules`, `README.md` | +| Public exports enabled | Verified | footer links `llms.txt`, `llms-full.txt` — rule 6 applies | +| Group-level OpenAPI | Verified | `groupSchema` accepts `openapi`, `asyncapi`, `tag`, `directory`, `expanded` alongside `pages` — generates a page per operation, no stub files | +| OpenAPI overlays | Verified | `openapi.overlays` takes Overlay documents applied in order; auto-discovered as well as explicit | +| `x-mint` extension | Verified | `metadata`, `content`, `pre`/`post`, `href`, `groups`, `playground.expand`, `mcp{enabled,name,description}`; plus `x-hidden`, `x-excluded`, `x-mint-enum` | +| Current API reference wiring | Verified | 219 `.mdx` stubs binding by `openapi: ` frontmatter — the legacy pattern, being replaced | +| OpenAPI CI | **Not working** | `.github/workflows/openapi-validate.yml` validates `openapi.yaml` at the docs-core root, which does not exist; no run history; names a different artifact from the remote spec `docs.json` reads. The real check today is `mint validate`. Out of scope to fix. | +| Other CLI checks | Verified, unexercised | `mint broken-links`, `a11y`, `test`, `export`, `format` | +| Publication authority, deploy-status API | Unverified | not determinable from the repo; §5 warns against inventing a Mintlify outbound webhook | + +**KB capabilities are entirely unverified** — endpoint, auth, claim reads, eligibility fields, +change discovery, contribution format, task status, ancestry preservation. Nothing has been +exercised. + +**Not treated as KB knowledge:** `~/.claude/skills/rfp/knowledge/prisma-airs-ai-gateway.md` is +an internal sales artifact, useful only for generating questions; and the existing published +corpus, per rule 7. + +**Left alone deliberately:** non-page files inside the build scope at the repo root +(`writing-style-guide.md`, `MCP-Gateway-Roadmap.md`, `create-split-prs.sh`, two stray images). +They parse cleanly so they raise no warning, but they are inside the public exports. Excluding +them changes existing published output, which is out of scope. + +--- + +## Naming rules + +Drawn from the RFP knowledge file's convention. Naming is the one area where the KB is not the +authority — it is an operator and branding decision. Everything else still is. + +**Renamed:** "Portkey" / "Portkey AI" as the product → **Prisma AIRS AI Gateway** on first +mention, then **the gateway** or **AI Gateway**. Management plane → **Strata Cloud Manager**. +Company → **Palo Alto Networks**. + +**Never renamed** — functional identifiers. A doc that breaks copy-paste is worse than one with +a legacy name in it. + +| Kind | Examples | +|---|---| +| Packages and imports | `portkey_ai`, `portkey-ai`, `from portkey_ai import Portkey` | +| Classes, constructors, constants | `Portkey(...)`, `createHeaders`, `PORTKEY_GATEWAY_URL` | +| Environment variables | `PORTKEY_API_KEY`, `PORTKEY_*` | +| HTTP headers | `x-portkey-api-key`, `x-portkey-provider`, `x-portkey-*` | +| Hostnames | `api.portkey.ai`, `app.portkey.ai` | +| Config keys, JSON fields, `operationId`s, schema names | as shipped | +| Repo names in changelogs | `Portkey-AI/gateway`, `Portkey-AI/albus`, … | + +> **If a reader would type it or a machine would parse it, it does not change.** If a reader +> only reads it, it does. + +**Also decided:** the `prisma-airs-cta` snippet is **not used anywhere in the Prisma AIRS +version.** It announces the Portkey → Prisma AIRS transition, which is redundant on pages that +are already Prisma AIRS. It stays on Latest-version pages. + +**Approved as written:** the open-source Gateway keeps its own identity; community CTAs +(Discord, `git.new/ai-gateway-docs`, `support@portkey.ai`, `status.portkey.ai`) stay as they +are; the compliance and uptime claims on `introduction/what-is-portkey` are Portkey-corpus and +not inherited. + +**Never run a global find-and-replace.** The identifier list guarantees it breaks code samples +across ~1,200 pages. The migration unit is a page, and the trigger is the grounding gate. + +--- + +## Page contracts + +Bound to this repo's components and [`writing-style-guide.md`](../../writing-style-guide.md). +Where the handoff and the style guide overlap they agree; where they differ the handoff's +requirements are additive — what must be present, not how to phrase it. + +| Type | Required elements | +|---|---| +| Concept | purpose · mechanism · **boundaries, including what it does not do** · applicability · next task | +| Quickstart | prerequisites before the first command · minimal steps · complete runnable example · **verification** · one next step | +| How-to | one goal · environment/version · steps · checks · **failure cases** | +| Reference | exact versioned contract · parameters · types · defaults · errors · examples | +| Operations | procedure · prerequisites · verification · **rollback** where production routing or credentials change | +| Troubleshooting | symptom *as the reader would describe it* · diagnostics · supported causes and remedies | +| Changelog | release identity/date · applicability · what changed · migration impact | +| Example | dependencies · complete runnable code · expected behaviour · supported version | + +The two most commonly skipped elements are **boundaries** on concept pages and **verification** +on quickstarts. "How does the reader know it worked?" is part of the contract. + +Only list troubleshooting causes the KB supports; speculative causes violate rule 5. + +**Components.** `` for language variants — never ``. `` for procedures, +``/`` for next actions, `` for collapsible detail, `` for +images, ``/``/``/`` for actionable constraints rather than +decoration. Prefer native components; propose the smallest remedy before adding custom +machinery. + +**Code style.** K&R braces, 4-space indent, simple objects on one line, no trailing commas in +Python, language-correct comments, every block titled so `CodeGroup` renders a usable tab label. +Complete and runnable with safe placeholders. Never a real credential. + +**Applicability has no public frontmatter home.** Decide before authoring: an in-page `` +callout, or a private manifest field only. Do not invent a frontmatter key Mintlify will not +validate. + +### Pre-publication checklist + +- [ ] Frontmatter valid; page registered in `docs.json`; route assigned; owner recorded +- [ ] Every substantive assertion has accepted, applicable KB support +- [ ] Public eligibility re-checked **now**, not at draft time +- [ ] No private material in the page, its metadata, or the public exports +- [ ] Examples syntax-checked; runnable tests run or the omission recorded +- [ ] Links and anchors resolve; next step is coherent +- [ ] `mint dev` reviewed on desktop and mobile +- [ ] Base-revision check — no concurrent human edit overwritten +- [ ] Editorial approval recorded; deployment status **verified**, not inferred from merge + +Two failure modes the gate must catch, both worse than a missing citation because they look +correct: a valid claim ID cited for an assertion it does not support, and an assertion stated +with more certainty or broader scope than its claim carries. + +--- + +## Provenance model + +Claims are tracked at **section/assertion** granularity so a changed fact patches one section +rather than rewriting a page. + +Manifests must not live in page frontmatter or under a built path. Storage, in preference +order: KB-side via MCP (best fit for §6, avoids a second truth store); a sibling private repo; +or a gitignored local path for the vertical slice only. Not the repo's existing `private/` +directory — despite the name it is tracked, and contains a real `.mdx`. + +```yaml +schema: docs.page.v2 +page_id: docs.ai-gateway.fallbacks +route: "product/ai-gateway/fallbacks" +type: guide # concept|quickstart|guide|reference|operations|troubleshooting|changelog|example +owner: "docs-owner" +applies_to: "supported-version" # version only — see deployment invariance +lifecycle: draft # draft|review|published|withdrawn +docs_revision: "git-sha" +kb_revision: "immutable-kb-revision" +sections: + - id: how-fallbacks-trigger + assertions: + - id: a1 + text_digest: "sha256-of-the-asserted-sentence" + claim_refs: + - id: "accepted-claim-id" + revision: "claim-revision-or-digest" + generated_by: "task-id" + origin_kind: generated # human|generated|mixed + reviewed_by: "review-reference" +publication: + build_id: "publication-id" + policy_revision: "policy-revision" + published_revision: "actually-served-revision" +``` + +`published_revision` is deliberately separate from `docs_revision`. §5: "A successful commit is +not proof that readers received the update." Without the split there is no way to express +*merged but readers still see the old page*. + +`text_digest` distinguishes an unchanged generated echo (no-op) from a human edit of generated +prose (submit the semantic delta, preserve ancestry). + +### Dependency index + +``` +claim_id -> [ {page_id, section_id, assertion_id, claim_revision_seen} ] +``` + +Derived from manifests, never hand-maintained. This — not the agent, not the scheduler — is +what makes the loop possible: without it, "a claim changed" means re-reading ~1,200 pages and +guessing relevance; with it, a dictionary lookup returns the exact section set. + +**It is a free byproduct of the grounding gate and prohibitively expensive to retrofit.** When +a page passes the gate the claim IDs are already known — that is what the gate checked. Writing +them to the manifest then costs nothing; reconstructing them later is indistinguishable from +inventing provenance. + +Two consequences. **Loop coverage equals migrated-page count** — unmigrated pages have no +manifests, so no claim change can point at them; the Prisma AIRS version's page count is +simultaneously the INIT 1 progress metric and the INIT 2 coverage metric. And the index is +**rebuildable rather than durable**, so a corrupted index is recoverable, not an outage — do +not add durability engineering to it. + +### Ledgers + +**Coverage** — every eligible public KB claim is in exactly one state: `used`, +`awaiting-placement`, `blocked`, or `omitted` *with a recorded reason*. The ledger exists so +"we chose not to document this" is distinguishable from "we missed it." + +**Disposition** — every change ends as `applied`, `no-op`, `excluded`, `pending-review`, +`conflict`, `blocked`, or `failed`. Nothing ends as "done" implicitly. + +| From | Event | To | +|---|---|---| +| — | Tier 0 detected | `no-op` | +| — | Tier 1/2 PR opened | `pending-review` | +| `pending-review` | merged **and published revision confirmed** | `applied` | +| `pending-review` | closed unmerged, reason recorded | `excluded` | +| — | Contradiction detected | `conflict` | +| — | Accepted but public eligibility absent | `blocked` | +| any | Submission or run error | `failed` (retry on the same idempotency key) | + +**Idempotency:** duplicate delivery must produce one logical contribution. Persist receipt +before acknowledgment. **An empty queue is not evidence of synchronization** — periodic +reconciliation compares KB state, source revisions, manifests and publication status regardless +of queue depth. That principle generalises to cursors and webhook deliveries alike. + +### Bootstrapping + +~1,200 pages exist with no manifests. Do not backfill — rule 7 forbids treating current prose +as support for its own claims. Manifests exist only for pages that passed the gate; everything +else is implicitly `unverified`, tracked as a count. That count will not reach zero in INIT 1, +and the exit report should say so plainly rather than scoping the corpus down to hide it. + +--- + +## Reconciliation loop + +**Not a self-updating docs set.** Rule 7 means an agent that both authors a claim and accepts +it has closed a loop with no external truth inside it — every iteration reinforces whatever the +first got wrong, and nothing can detect that. §5 forbids last-write-wins from the other side. + +So the agent is a **divergence detector that opens pull requests**. It never merges, never +pushes to `main`, never force-pushes, never publishes. Blast radius is an open PR. + +### Topology: KB ↔ spec ↔ docs + +Three nodes, since the spec became a co-equal trusted source. Drift is **symmetric** — the loop +raises a divergence regardless of which artifact moved; "the spec is newer" is not a +resolution. Resolution is **always human**: a KB↔spec contradiction has no diff to review, so +it inherits tier-3 handling. Webhooks on both sides make polling the backstop rather than the +mechanism — but keep scheduled reconciliation, because a missed delivery is exactly as silent +as a missed cursor event. Webhooks reduce latency; reconciliation establishes truth. + +The join key for spec drift is `x-airs-provenance` on the operation. Without a claim reference +there, nothing can observe that the KB moved and the spec did not. + +For KB↔docs: **reconcile against the manifests, always.** `claim_revision_seen` already *is* +the previous snapshot, so there is no second store to build and no cursor-vs-snapshot fork to +choose. If a cursor exists, use it only to narrow which claims to re-read. Cost is bounded by +coverage, not by KB size. + +### Triage tiers + +If every change needs a careful human read, review fatigue ends the loop in weeks. Volume has +to be absorbed unevenly. + +| Tier | Trigger | Action | Human | +|---|---|---|---| +| **0 — echo** | Revision changed, normalized digest identical | Update `claim_revision_seen`. No PR. | None | +| **1 — substitution** | Single templated slot: limit, default, version string, enum member | Auto-PR, one-value diff, body quotes both claims and the claim ID | Merge only | +| **2 — rewrite** | Behaviour change, new capability, deprecation | Draft PR: stale sections marked, claims quoted verbatim, prose labeled a proposal | Factual then editorial review | +| **3 — conflict** | Claim retracted; two accepted claims contradict; eligibility revoked | **No PR.** Issue with a default assignee, disposition `conflict` or `blocked` | §10 withdrawal path | + +Tier assignment is mechanical — a digest and manifest comparison. Ambiguity escalates; nothing +is demoted by inference; there is no path from tier 3 to a pull request. + +Tier 0 carries most of the volume and its value is entirely in what it does *not* generate. +Tier 3 gets under-designed: a release changing a documented default **contradicts an accepted +claim by construction**. That is the normal path, not an edge case, which is why `supersedes` +in the release-assertion block matters more than any other field — a tier-3 event arriving as +an untagged tier-2 event silently publishes a contradiction. + +### Runtime (Q10) + +**Scheduler:** GitHub Actions cron invoking `claude -p`, with `repository_dispatch` for +webhooks. The output artifact is a pull request, so the scheduler should live where the +artifact lives; anything else moves credentials across a boundary for no gain. Revisit only if +the KB endpoint is unreachable from GitHub-hosted runners — a network question for Q2. +A long-lived daemon buys nothing: the work is bursty and event-shaped. + +**Budgets:** three ceilings per run — claims examined, PRs opened, hard token budget. On +breach: stop, alert, resume next run. Safe *because* of the idempotency key — a partial run is +replayable, so a budget stop costs latency rather than correctness. + +**Notifications:** tier 3 opens a **GitHub issue**, not a message. A `conflict` is a decision +not yet made, so it needs a durable work item with an owner and a close state. A chat ping +scrolls away and orphans the ledger entry. + +**Safety:** idempotency key `(claim_id, claim_digest, page_id, section_id)`; persist the +watermark *after* the PR exists so a crash re-does rather than skips; a kill switch checked at +the top of every run; a rate ceiling so a bulk re-import touching 400 claims alerts instead of +opening 400 PRs; no self-merge, no `main` write, no force-push, stated in the workflow +permissions block and not only in prose. + +**Review capacity is not a problem** — an earlier draft claimed it was, reasoning from Q7's +single-owner assignment, and that was wrong. Tier 1 is a string comparison against a quoted +claim; tier 2 is ordinary docs review. The repo's last fifteen merges had ~8 distinct reviewers +and no `CODEOWNERS`; review happens anyway. What survives is narrower: tier-3 issues have no +forcing function the way a blocking PR does, so they need a **default assignee**. + +### Echo contamination + +The failure mode most likely to cause real damage and the only one invisible from inside the +loop. Published pages get crawled; if generated documentation re-enters the KB as evidence, the +agent confirms its own prior output, confidence rises, and drift compounds with no error +anywhere. + +`origin_kind` and `generated_by` in the manifest are half the mechanism. The other half is +ingestion **refusing** generated-ancestry content as corroborating evidence. Preservation is +not the requirement — metadata nothing acts on changes no outcome. Confirmed a **hard +prerequisite** (Q11): the loop does not run against production KB until that code path has been +seen. + +### Instrumentation + +| Metric | Why | +|---|---| +| **Staleness budget** — sections whose `claim_revision_seen` lags the KB, bucketed by age | Primary health signal. Should oscillate, not climb. | +| Open handles by age | Catches a submission accepted then forgotten | +| Tier distribution per run | A tier-2 spike usually means a KB re-import, not a product change | +| Runs since last successful KB read | Distinguishes "nothing changed" from "we stopped looking" | +| Open tier-3 issue age | The one queue with no forcing function | +| `conflict` count, never aggregated away | Each is a decision not yet made | + +Do not assume anyone reads a dashboard. Wire thresholds into a **self-reporting health check**: +when one is breached, the loop opens an issue about itself. A PR queue is structurally incapable +of reporting that the loop stopped opening PRs — "no PRs this week" reads identically to healthy +and to broken. + +### Build order + +Ordered by blast radius, not difficulty. + +1. **On Q2.** Read the claim and change-discovery contract. +2. **On Q11.** Verify ingestion refuses generated ancestry. Do not run against production KB + until then. +3. Dependency index as a grounding-gate output — worth doing even if the loop is never built, + since it makes manual impact analysis deterministic. +4. Tier 0 only, in report mode: detect and log, create nothing. Real data, zero blast radius. +5. Tier 1 auto-PRs behind the rate ceiling and kill switch. +6. Tier 2 draft PRs; tier 3 issues with a default assignee. +7. Self-reporting health check. +8. Reconciliation sweep for stale handles. + +Tier 2 is the most interesting to build and should be built last. + +--- + +## Changelog contribution path + +The INIT 2 pilot, because changelogs are the one place docs legitimately *originate* knowledge +(§4) rather than consuming it — so the contribution direction is exercised without an authority +conflict. The facts are small, dated and discrete; the workflow already exists in +`.claude/skills/update-changelog/SKILL.md`; and an append-only historical entry has low blast +radius in a way a wrong quickstart does not. + +**Done.** Step 4a emits an assertion file per release to `_project/releases/@.yaml`: + +```yaml +release: + id: "gateway-enterprise-node@v2.21.0" + repo: "Portkey-AI/gateway-enterprise-node" + date: "2026-08-14" + source_revision: "" +assertions: + - id: r1 + text: "" + kind: new-capability # new-capability|behavior-change|default-change|fix|deprecation + applies_to: "" + supersedes: [] # empty if net-new + affects: [] +``` + +One assertion per *fact*, not per PR. State the fact, not the edit. `supersedes` is the field +that matters: a release that changes a default does not merely add a fact, it invalidates one, +and that invalidation is what marks existing pages stale. These are review artifacts today and +the docs→KB payload once MCP access exists. Nothing is backfilled — rule 7 again. + +**Done.** Step 7 split into two outputs on two clocks: the `` changelog entry is +**immutable** once published (corrections append), while guide and reference patches are +mutable and gated normally. Separate commits. + +**Publication policy (Q9).** The §4 default — publication waits for KB acceptance — would make +the changelog lag every release by the KB review latency. §4 permits an explicit release-only +exception, and it is approved: **changelog entries publish on the release schedule** with the +KB proposal submitted simultaneously; **guide and reference patches wait for acceptance, no +exception.** Narrow, and scoped to a page type whose content is inherently a dated observation +rather than a standing product claim. + +**Remaining.** Step 4b — MCP submission with idempotency on release id + digest, provenance +(`origin: engineering-release`, `origin_kind: human`, authenticated actor, source revision), +receipt persisted before acknowledgment. And replacing step 4's grep-based doc-impact search +with the dependency index; `affects` is the manual stand-in until then. + +--- + +## Known gaps + +The detailed journey-by-journey route inventory has been dropped — Vrushank is hand-designing +the skeleton, which supersedes it. What survives is the gap register. + +- **Grounding is unknown, not absent.** Every existing feature page carries defaults, limits + and precedence rules with no claim references. Under §3 they are all unsupported until + reconciled. This is the largest item of INIT 1 work by volume. +- **No applicability metadata.** Pages state no supported version. (Environment is *not* part + of this gap — see deployment invariance.) +- **Troubleshooting is the weakest surface.** Reliability features have configuration pages but + no symptom→diagnosis→remedy path; no day-2 operations pages (key rotation, budget breach, + provider outage, guardrail false-positive triage); content split across `support/`, + `help-center/` and `self-hosting/` with no single entry point. +- **Limits and errors are not consolidated.** No single rate-limit / quota / error-code + reference. +- **Changelog contract compliance unaudited** against §2's required elements. + +**To put to the KB, not findings:** the RFP knowledge file describes a four-tier tenancy +hierarchy (Organisation → Department → Team → User/Application) where the docs describe +organizations and workspaces; and it uses licensing labels (Enterprise, Agent Gateway, +Observability Suite, Guardrails Engine, Model Catalog, Prompt Studio) that only partly match +the navigation groups. Confirm which vocabulary is public before applying either. + +--- + +## Feedback for the brief + +From implementing against v2. Ordered by cost incurred. Fold into the next revision rather than +keeping as a separate versioned document. + +**1. §2's privacy warning is too soft, and it caused the failure it warns about.** "A page +absent from navigation is not necessarily private" reads as *usually is, with exceptions*. The +truth is binary: navigation omission provides **no** exclusion. I believed the soft reading, +wrote it into three planning documents, and put the brief itself inside the build scope — +`mint validate` caught it on a parse error. Every planning artifact here was headed for +`llms-full.txt`. Name `.mintignore` as the mechanism, and prescribe verifying exclusion with a +deliberately malformed file in the excluded path: "no error" is a weak signal unless you first +confirm the tool *would* have errored. + +**2. "Sole factual authority" does not survive contact.** The spec turned out to be a second +trusted source the KB does not own. The brief has no vocabulary for this, so the exemption, +symmetric-drift rule and maintainer conflict procedure were invented mid-flight, and the loop +was redesigned from two-node to three. Replace rule 1 with a **trusted source register** — +enumerated sources, each with a domain, owner and conflict procedure, KB still primary. The +single-authority framing actively encourages treating a second source as a violation to +minimise rather than an architecture to design. + +**3. Preserving generated ancestry is not the requirement; refusing it is.** §5 asks for +preservation, rule 7 states the principle, and the brief never connects them. As written, an +implementer can satisfy both completely and still ship a system where documentation silently +corroborates itself. State the enforcement point: rule 7 is enforced at ingestion, and +acceptance requires demonstrating the code path that reads the ancestry field and declines the +content. Lowest cost so far, highest consequence — the failure raises confidence while lowering +accuracy, so it looks like health from inside. + +**4. No "establish platform capabilities" step.** "Mintlify is the platform, build no +infrastructure" is correct and saved real work, but it never says *find out what the platform +already does before designing around it.* So the structure/prose split was designed as an +authoring discipline before `openapi.overlays` turned up, which implements it natively as two +files with two owners. A native implementation beats a documented discipline every time. The +same gap produced the `.mintignore` failure. + +**5. Nothing addresses the disposition of an existing corpus.** The brief reads as though the +docs are being created from nothing; ~1,200 pages already existed under another brand, and +everything was blocked until the operator ruled. Add a required per-corpus choice, and note +that **re-ground, do not inherit** takes legacy defects out of scope by construction rather +than by triage. Worth more than any other single day-one answer. + +**6. The scoped-exception mechanism is used twice and named zero times.** §4's release-only +policy exception is a general construct presented as a one-off; the OpenAPI exemption needed +the identical shape. Name it once — scope, rationale, review date, explicit non-precedence. + +**7. "Factual review" is described as a role when it is often a mechanical check.** This led me +to the review-bottleneck error above. Distinguish assertions needing **judgement** from those +verifiable by **comparison**; only the former needs a named owner, and the latter is a +well-formed PR body, which is tooling rather than staffing. + +**8. Smaller.** The useful progress metric turned out to be *pages past the gate*, which is +also loop coverage — name it. §6's "proceed while access is pending" envelope is far larger +than it sounds and worth stating explicitly, since underestimating it delays undependent work. +§9's reconciliation accounting is two-party and needs to generalise to N sources. And prompt +early for environment invariance: it is a large simplification when true, and assuming variance +is expensive. + +### What held up + +Worth keeping while fixing the above. **Rule 7** is the best idea in the brief and should not +be softened. **"Ask only what remains needed after inspecting configured access"** produced +better questions than a standard intake, because it forced the repository to be read first. +**The disposition ledger's insistence that nothing ends implicitly** matters most for the states +nobody plans for — `conflict` and `blocked` are the normal path once releases start changing +defaults. And **"an empty queue is not evidence of synchronization"** generalised further than +written: it covers cursors and webhook deliveries, and it is why scheduled reconciliation +survives push triggers on both sides. + +--- + +## Layout + +``` +prisma-airs/ +├── _project/ +│ ├── README.md this file — the canonical doc +│ ├── openapi-handoff.md instructions for the spec-repo agent +│ ├── brainstorm.md + brainstorm.html presentation design brainstorm + wireframe +│ ├── prisma-airs-docs-mintlify-handoff-v2.md the source brief +│ └── releases/ per-release assertion YAML (generated) +└── overview.mdx published — the Prisma AIRS version seed +``` + +`_project/` is excluded from the build by the repo-root `.mintignore`. Release assertion files +live here rather than in `changelog/` because they are not pages — they are not secret, since +everything in them becomes public in the changelog entry anyway. diff --git a/prisma-airs/_project/brainstorm.html b/prisma-airs/_project/brainstorm.html new file mode 100644 index 00000000..1d4f92d6 --- /dev/null +++ b/prisma-airs/_project/brainstorm.html @@ -0,0 +1,566 @@ + + + + + +Prisma AIRS AI Gateway — docs wireframe + + + + +
+
Prisma AIRS AI Gateway · docs wireframe · brainstorm, not a decision
+ +
+ +
+ +

Docs presentation wireframe

+

Companion to brainstorm.md. Low-fidelity on purpose — this is about +layout, hierarchy and where the reader's eye lands, not final visuals.

+ +
+ Every label here is a placeholder. Nothing in this file is a grounded product + claim, and no text should be lifted into a published page. The accent colour + #FA582D stands in for the PANW palette and needs confirming with brand. + The navigation groupings are worked examples to react to — the skeleton is yours to design. +
+ + +

01Home — a decision surface, not a directory

+

Four readers, four doors, one screen. Each door reaches something verifiable in +about two minutes. No table of contents above the fold.

+ +
+
+ docs.paloaltonetworks.com/prisma-airs/ai-gateway
+
+ +
+
Search the gateway docs… ⌘K
+ ChangelogStatus + Open console +
+
+
+
+
Put every model call behind one control point.
+

One paragraph. What it is, where it sits, who it is for. + No feature list, no logo wall.

+
+ +
+
Send your first request + Developer · ~2 min to a response body
+
Enforce a policy + Security owner · see a request blocked
+
Provision an org + Admin · models, budgets, keys
+
How it works + Architect · the data path, and its edges
+
+ +
The request path
+
+
Your appSDK or REST
+
Gatewayroute · cache · retry
+
Policyguardrails
+
Providerany model
+
+
Observability & audit + logs · traces · spend · evidence
+

Reused on every concept page, with the current subject highlighted. + Anything outside these boxes is something the gateway does not do — boundaries shown, not claimed.

+ +
If you read three pages
+
+
ArchitectureWhere it sits and what it terminates
+
DeploymentManaged and hybrid — same behaviour
+
Controls & evidenceWhat you can enforce and prove
+
+
+
+
+ +
+
1
No sidebar on home. A sidebar on a landing page invites + scanning for a familiar word instead of choosing an intent.
+
2
Doors are labelled by intent, not artifact. + "Send your first request", not "Quickstart".
+
3
The diagram is the second thing on the page — it is the + mental model the other three readers need before any procedure makes sense.
+
4
One navbar CTA. navbar.primary takes a typed + button; everything else is a plain link.
+
+ + +

02Quickstart — the verification block is the point

+

Prerequisites before any command. One complete runnable example per language, +not a fragment per step. Then proof, then exactly one next step.

+ +
+
+
+
Search… ⌘K
Open console
+
Docs
API reference
Integrations
Changelog
+
+
+
Get started
+
Overview
First request
Concepts
+
Route
+
Providers
Fallbacks
Caching
+
Govern
+
Guardrails
Budgets
+
Operate
+
Runbooks
Troubleshooting
+
+
+
Get started  ›  First request
+
Send your first request
+

One sentence on what will exist at the end of this page.

+ +
Before you start + An API key · a configured provider · Python 3.9+ or Node 18+
+ +
Make the call
+
+
PythonNode.jscURLREST
+
+ from portkey_ai import Portkey

+ client = Portkey(api_key="$PORTKEY_API_KEY")
+ response = client.chat.completions.create(…)
+ print(response.choices[0].message.content) +
+
+

Complete and runnable, with placeholder credentials — never a fragment, + never a real key. Identifiers such as portkey_ai and PORTKEY_API_KEY + do not get renamed.

+ +
Check that it worked
+
Expected + A completion in the response body, and one new entry in the console log view.
+

The most-skipped element of the page contract, and the one that decides whether + the reader trusts the next page.

+ +
Next
+
+
Add a fallbackSurvive a provider outage
+
Attach a guardrailBlock a request by policy
+
+
+
+
On this page
+
Before you start
Make the call
Check that it worked
Next
+
+
Take with you
+
Copy page
Open in Claude
Open in Cursor
Add MCP server
+
+
+
+
+ +
+
1
Four tabs, not seven. The Latest version carries seven; + each one costs the reader a scan.
+
2
Sidebar groups are verbs — Route, Govern, Operate. + Verbs survive a feature rename; nouns do not.
+
3
"Take with you" is the contextual menu, promoted + into the TOC rail rather than hidden behind an icon. Four options are enabled today; the schema + offers MCP, Cursor, VS Code, PDF and spec download.
+
+ + +

03Concept — orientation first, boundaries required

+

Same diagram, current subject highlighted. "What this does not do" is a required +heading, not an afterthought.

+ +
+
+
+
Route
+
Providers
Fallbacks
Load balancing
+
Caching
Retries
+
+
+
Route  ›  Fallbacks
+
Fallbacks
+
+
Your app
+
Gatewayyou are here
+
Policy
+
Provider
+
+ +
What it is
+
+
How it works
+
+
What it does not do
+
Boundaries + The explicit limits. Skipped everywhere in the current corpus, and the section + evaluators read first.
+
When to use it
+
+
Next
+
Configure a fallbackHow-to
+
RetriesRelated concept
+
+
On this page
+
What it is
How it works
What it does not do
+
When to use it
Next
+
+
+ + +

04API reference — generated, three-column, params open

+

No stub files. Generated from the spec via group-level openapi with a +prose overlay. The right rail is a persistent request/response panel — the Panel +slot is unused anywhere in the corpus today.

+ +
+
Docs
API reference
Integrations
Changelog
+
+
+
Chat
+
Create completion
Stream completion
+
Embeddings
Create embedding
+
Files
Upload
List
+

Groups generated from spec tags — + tag design is information architecture.

+
+
+
Chat
+
+ POST Create completion
+

/v1/chat/completions — description empty until the KB supports it. + Empty beats invented.

+
Body
+ + + + + +
FieldType
modelstringrequired
messagesarrayrequired
streambooleanoptional
+

Set api.params.expanded: "all" on core endpoints. + Collapsed parameters hide exactly what the reader came for.

+
+
+
Try it
+
cURLPyJS
+
curl -X POST \
  $BASE/v1/chat/…
+
200
+
{ "id": …,
  "choices": […] }
+
Download spec
+
+
+
+ + +

05Admin runbook — the archetype the corpus is missing

+

Not a feature page. Steps, a verification per step, a rollback, and what breaks if +you get it wrong. Admins are the reader served worst today.

+ +
+
+
+
Runbooks
+
Rotate a provider key
Budget breach
+
Provider failover
Guardrail false positives
+
Onboard a workspace
+
+
+
Operate  ›  Runbooks
+
Rotate a provider key
+
Production impact + Touches live routing. Read the rollback section before starting.
+
+
1 · Add the new credential
+
Verify + Both credentials listed, new one inactive.
+
2 · Shift traffic
+
Verify + Logs show the new credential ID; error rate flat.
+
3 · Retire the old credential
+
+
Rollback
+
If step 2 raises errors + Reverse the shift. Required on any page that changes production routing or credentials.
+
+
+
+ + +

06Troubleshooting — indexed by symptom, deep-linkable

+

Headed by what the reader would actually type. One accordion per symptom, expanded +on anchor link, so support can send a link straight to the answer.

+ +
+
+
Operate
Runbooks
+
Troubleshooting
Errors & limits
+
+
Troubleshooting
+

Find the symptom. Every entry links from an error code and from support.

+
+
+ “My requests suddenly return 429”＋
+
+
“A guardrail is blocking valid traffic”－
+
+

Only causes the KB supports. Speculative causes + are inventions with a friendly face.

+
+ “Latency jumped after enabling caching”＋
+
+
+
+
+ + +

07Identity — the knobs, and the one that is broken

+ +
+

accent · placeholder
confirm w/ brand

+

current primary
#0891B2

+

ink

+

panel

+

shade

+

line

+
+ + + + + + + + + + + + + + + + + + + + + + + +
KeyNowThought
colorsprimary / light / dark all #0891B2A defect, not a preference. light renders on dark backgrounds and + dark on light. Identical values mean neither mode gets a contrast-adapted accent.
thememintNine available — mint, maple, palm, willow, + linden, almond, aspen, luma, sequoia. + Changes chrome geometry, not just colour. Cheapest large visual change on the list.
fontsunsetSplits heading / body; self-hosted woff2 supported, + so PANW brand type needs no Google Fonts dependency.
icons.libraryunset → fontawesomelucide or tabler. Lighter stroke suits a security brand. + 567 <Icon> uses make this a visible choice.
background.decorationgradientgrid reads infrastructure; gradient reads consumer SaaS.
styling.codeblockssystemAccepts a named Shiki theme, or dark always — permanently dark code on a light + page is a strong, deliberate look.
thumbnailsunsetSocial / OG cards. Every shared link is currently an unbranded auto-card. Cheap, highly visible.
search.promptunsetFree personality, zero cost.
markdown.instructionsunsetMost underused key in the schema. Appended to every page served to AI agents — + the place to state the naming rule so an agent reading one page does not invent a rename.
bannerPortkey webinarRetire it and leave the slot empty. A banner that always says something says nothing — + and it is the channel an urgent withdrawal notice needs.
+ + +

08Component discipline — measured across the current corpus

+ + + + + + + + + + + + + + + +
ComponentUsesRead
<Card>3005~2.5 per page. Card soup — used everywhere, they stop being seen. Cap at two groups per page: + one hub, one next-steps.
<Tabs> vs <CodeGroup>707 / 611The style guide says CodeGroup for language variants; the corpus does the opposite half the + time. Tabs hide content from in-page search and agent-facing markdown.
<Frame>997Almost all screenshots. They rot, and they orient nobody who has not logged in. One diagram + outperforms a hundred.
<Accordion>842Often prose hidden because the page is too long. Collapsing does not shorten a page, + it makes it unsearchable by eye.
<Check>48The tell that quickstarts skip verification. Should rise sharply.
<Columns> · <Panel>1 · 0Effectively unused. Panel is exactly what an API page wants.
+ +

Also worth a linter, not a fix: +product/ai-gateway.mdx carries gsidebarTitle: in its frontmatter — a typo +that has silently done nothing. Mintlify ignores unknown keys, so frontmatter mistakes are invisible +to review. Validate frontmatter against the page-contract schema in CI instead.

+ + +

09What can ship before KB access

+

The visual identity work makes no product claim, so none of it is blocked by the +grounding gate. It is the one substantial thing that can move at full speed right now.

+ +
+
Unblocked today + Colours (fix the light/dark defect) · logo · fonts · theme · icons · + search.prompt · thumbnails · contextual · + markdown.instructions · retire the banner · the data-path diagram · + component rules in the page contracts
+
Waiting on your skeleton + Navigation primitive — products vs tabs vs anchors + vs staying a version · tab count · home page composition · sidebar grouping
+
Waiting on the KB (Q2) + Every word of body copy, on every page. Including — especially — the API descriptions.
+
+ +

10Open questions

+
+
✓
Version or product? — answered 2026-09-07. Stays a + versions[] entry for now. Revisit trigger is route stability, not page count: + moving off versions later costs a redirect for every published route, so the + moment to reconsider is before the first substantial batch publishes.
+
2
Brand latitude — track PANW exactly, or a + docs-appropriate interpretation?
+
3
Is there a console URL worth a navbar primary button + at launch?
+
4
Do security reviewers need PDF export? One line to enable, + but it changes how pages should be written — hover states and live links read badly on paper.
+
5
Do the four readers match how this is actually sold? + Derived from the corpus and the RFP artifact, which is a sales document rather than a KB source. + The assumption most likely to be wrong, and cheapest to correct now.
+
+ +
+ + diff --git a/prisma-airs/_project/brainstorm.md b/prisma-airs/_project/brainstorm.md new file mode 100644 index 00000000..f5d41973 --- /dev/null +++ b/prisma-airs/_project/brainstorm.md @@ -0,0 +1,251 @@ +# Brainstorm: what the Prisma AIRS AI Gateway docs should feel like + +A design brainstorm, not a decision. Written 2026-09-07 alongside +[`brainstorm.html`](./brainstorm.html), a wireframe of the same ideas. + +**Scope note.** Launch scope and the navigation skeleton are yours to design. So this is about +*presentation* — chrome, typography, page archetypes, component discipline, and the Mintlify +capability surface you have to design against. Where structure appears it is a worked example +to react to, not a proposal to adopt. Every label in the wireframe is a placeholder; none is a +grounded product claim. + +Everything about Mintlify below was verified against the installed CLI **4.2.876** and the +current `docs.json`. Web access is blocked from this workspace, so treat version-specific +details as accurate for this CLI and worth confirming before relying on the fine points. + +--- + +## 1. Four readers who want four different first pages + +| Reader | Arrives asking | Fails when | Reads like | +|---|---|---|---| +| **Developer** | "How do I route a call through this?" | The first code block is 40 lines and needs a console visit first | Skims to the code, copies, runs, leaves | +| **Gateway admin** | "How do I provision, budget, and rotate safely?" | The page describes a feature instead of a procedure | Follows steps literally, needs to know it worked | +| **Security / governance owner** | "What can I enforce, and what evidence do I get?" | Controls are scattered across guardrails, admin, and enterprise sections | Wants coverage, not tutorials | +| **Evaluator / architect** | "What is this, where does it sit, what doesn't it do?" | Boundaries are missing and every page is a how-to | Reads three pages and forms a verdict | + +These four cannot share a landing page that is a table of contents. A table of contents serves +whoever already knows the vocabulary — which is none of them on day one. + +**The observation that should drive the design:** all four ask a variant of the same question — +*does this do what I need, and how fast can I see it for myself?* That is one design problem, +not four. + +## 2. Three organising bets + +### Bet 1 — the home page is a decision surface, not a directory + +One screen, four doors, each labeled by intent rather than by artifact type. "Send your first +request" beats "Quickstart"; "Enforce a policy across every model" beats "Guardrails". Each +door leads to a path that reaches something **verifiable** in about two minutes — a response +body, a blocked request, a log entry, a diagram. + +The measure of the home page is not how much it links to. It is how many readers reach a proof +without a second decision. + +### Bet 2 — show the data path, everywhere + +This is a product that sits *in* the request path. That is the whole mental model, and it is +spatial. One canonical diagram — request → policy evaluation → provider → response, with +observability tapping the middle — rendered light and dark, reused on every concept page with +the current subject highlighted. + +"You are here" orientation is the single highest-leverage asset on a docs site for an +inline-infrastructure product, and it is cheap: one SVG pair, authored once. The corpus today +has 997 `` instances, almost all product screenshots. Screenshots age badly and orient +nobody; one diagram does more work than a hundred of them. + +Corollary: it is also the honest way to state boundaries. Anything outside the box on the +diagram is something the gateway does not do, shown rather than claimed. + +### Bet 3 — treat the AI agent as a first-class reader + +Mintlify gives you `llms.txt`, `llms-full.txt`, per-page markdown served to agents, +`markdown.instructions` (custom guidance appended to every agent-facing page), and +`contextual.options` for open-in-Claude / MCP / Cursor / VS Code. Currently four of those +options are enabled and `markdown.instructions` is unset. + +For a product whose users are *building agents*, docs that agents consume well is both +on-brand and genuinely differentiating. Most vendor docs treat this as an export checkbox. +Concretely: set `markdown.instructions` to state the naming rule (the `PORTKEY_*` identifiers +that survive rebranding), the base URL, and the fact that examples use placeholder +credentials — so an agent reading one page in isolation does not hallucinate a rename. + +This also feeds back into grounding. `llms-full.txt` is where an ungrounded assertion does the +most damage, because it is read without the surrounding page to qualify it. + +--- + +## 3. The aesthetic levers, verified + +Current value versus what I would reach for. All confirmed present in this CLI's schema. + +| Lever | Now | Thought | +|---|---|---| +| `theme` | `mint` | Nine exist: `mint`, `maple`, `palm`, `willow`, `linden`, `almond`, `aspen`, `luma`, `sequoia`. Worth screenshotting all nine before defaulting. Theme changes chrome geometry, not just colour — cheapest large visual change available. | +| `colors` | primary/light/dark all `#0891B2` | **A real defect, not a preference.** `light` renders on dark backgrounds and `dark` on light; setting all three identical means neither mode gets a contrast-adapted accent. Needs the PANW palette with a genuinely lighter and darker variant. | +| `logo` | Portkey + PANW lockup, light/dark | Replace with the Prisma AIRS lockup. Set `logo.href` deliberately — the product page, not the docs home. | +| `fonts` | unset (system) | Splits into `heading` and `body`. PANW brand typography here is a large, cheap identity win; self-hosted `woff2` is supported, so no Google Fonts dependency. | +| `icons` | unset (`fontawesome`) | `lucide` and `tabler` are available. Lucide's lighter stroke reads better next to a security brand than FontAwesome's solid glyphs. Purely taste — but the corpus has 567 `` uses, so it is a visible taste. | +| `background` | `{ decoration: "gradient" }` | `gradient` \| `grid` \| `windows`, plus a light/dark `image` pair. `grid` suits infrastructure products; gradient reads consumer-SaaS. | +| `styling.eyebrows` | `breadcrumbs` | Keep. With four reader paths, position matters more than section name. | +| `styling.codeblocks` | `system` | Accepts a named Shiki theme. Pinning one (rather than following light/dark) makes code the strongest fixed element on every page. Worth trying `dark` — permanently dark code blocks against a light page is a strong, deliberate look. | +| `banner` | Portkey webinar, dismissible | Types are `info` \| `warning` \| `critical` with a colour override. Reserve it: a banner that always says something says nothing. Real use is a migration notice or an incident. | +| `navbar` | 3 links, no primary | `primary` supports a typed button. One CTA — console sign-in, most likely. Typed `github` / `discord` link variants render properly rather than as text. | +| `footer` | socials + link columns | Already has a "For LLMs" column pointing at `llms.txt`. Genuinely good; keep it and make it more prominent. | +| `search.prompt` | unset | Free personality with zero cost. "Search the gateway docs…" beats the default. | +| `contextual.options` | copy, view, chatgpt, claude | Add `mcp`, `add-mcp`, `cursor`, `vscode`, and `download-spec` on API pages. `download-pdf` matters more than it looks — security reviewers circulate PDFs. | +| `thumbnails` | unset | Controls social/OG cards: appearance, background image, font family. Every shared docs link is currently an unbranded auto-card. Cheap, high visibility. | +| `interaction.drilldown` | `true` | Keep. Expanding a group lands on its overview instead of nothing. | +| `markdown.instructions` | unset | See bet 3. Probably the most underused key in the whole schema. | +| `api.params.expanded` | unset (`closed`) | Consider `all` on core endpoints. Collapsed parameters hide exactly what a developer came to read. `api.params.post` adds "post pills" to `ParamField` from arbitrary spec keys — a hook for surfacing `x-airs-*` metadata inline. | +| `seo.indexing` | `navigable` | Correct. Only navigable pages get indexed. | + +### Navigation primitives available + +The top level of `navigation` accepts exactly one of: `products`, `languages`, `versions`, +`tabs`, `dropdowns`, `anchors`, `groups`, `pages`. This repo uses `versions` — three of them, +which is why Prisma AIRS currently sits as a peer of "Latest" and "Virtual Keys (Deprecated)". + +**Settled 2026-09-07 (Q14): stays a version, for now.** So the version switcher is the reader's +top-level control at launch, and the sections below are the alternatives to revisit against +rather than options to choose from. The one thing worth holding onto is the revisit trigger: +route stability, not page count — moving off `versions` later means a redirect for every +published page, so the moment to reconsider is *before* the first substantial batch publishes +and acquires inbound links. + +Rough shape of the tradeoff, for whenever that revisit happens: + +- **`products`** — strongest separation, own sidebar and identity per product. Right if AI + Gateway, MCP Gateway and Prompt Studio are sold and adopted separately. +- **`tabs`** — one product, several surfaces (Docs / API / Integrations). What Latest uses, + with seven tabs, which is two or three too many. +- **`anchors`** — persistent icon rail beside the sidebar. Good for the two or three + destinations every reader eventually needs (API reference, changelog, status). +- **`dropdowns`** — compact, hides structure. Best when the reader already knows the map. +- **`versions`** — reserve for actual product versions. + +Groups also accept `openapi`, `tag`, `directory`, `expanded` and `icon`, which is how the API +reference stops being 219 hand-written stubs — see [`openapi-handoff.md`](./openapi-handoff.md). + +--- + +## 4. Component discipline + +Measured across the current corpus: + +``` +3005 2166 997 842 810 + 707 686 611 567 517 + 356 267 203 172 + 122 118 93 48 43 + 40 4 1 +``` + +Three things jump out. + +**Card soup.** 3005 cards is roughly 2.5 per page. Cards are a navigational affordance; used +everywhere they become visual noise and the reader stops seeing them. Rule worth adopting: a +`` appears at most twice per page — once as a hub, once as next steps — and never +as a substitute for prose. + +**707 `` against 611 ``.** The style guide already says `CodeGroup` for +language variants, and the corpus does the opposite about half the time. `Tabs` hides content +from in-page search and from the agent-facing markdown; `CodeGroup` is understood as language +selection and syncs across the page. Worth enforcing in review rather than restating. + +**Underused and worth reaching for:** `` (once, in the whole corpus), `` +for nested response objects, `` for changelog entries — and `` at 48 uses, which +is the tell that quickstarts are skipping the verification step the page contract requires. +"How do you know it worked" deserves a distinct visual. + +**One anti-pattern to name:** `` at 842 uses is often prose hidden because the page +is too long. Collapsing content does not shorten a page, it just makes it unsearchable by eye. +Accordions are for genuinely optional detail — alternate platforms, deep error tables. + +**Also worth a linter, not a fix:** `product/ai-gateway.mdx` has `gsidebarTitle:` in its +frontmatter — a typo that has silently done nothing for however long. Mintlify ignores unknown +keys, so frontmatter mistakes are invisible. That is a good argument for validating frontmatter +against the page-contract schema in CI rather than trusting review. + +--- + +## 5. Page archetypes + +Six shapes cover almost everything. Wireframes for each are in `brainstorm.html`. + +**Home** — the decision surface from bet 1. `mode: "custom"` or `"wide"`, no sidebar, four +intent doors above the fold, the data-path diagram below, then a strip of "if you only read +three pages" for evaluators. + +**Quickstart** — prerequisites as a `` list before any command; one `` +carrying the full runnable example in each language, not a fragment per step; a **verification +block** that is visually distinct and shows the actual expected output; exactly one next step. +The current corpus's quickstarts mostly end at "you made a request" with nothing to compare +against. + +**Concept** — the data-path diagram with this subject highlighted, then mechanism, then a +boundaries section that is a *required heading* and not an afterthought. Boundaries are the +most-skipped element of the page contract and the most valuable to evaluators. + +**API reference** — generated from the spec, three-column with a persistent request/response +panel. `expanded: "all"` on core endpoints. The `` slot is currently unused anywhere in +the corpus and it is exactly what an API page wants. + +**Admin runbook** — the archetype the corpus is missing entirely. Not a feature page: +`` with a verification per step, a rollback section, and a "what breaks if you get this +wrong" callout. Key rotation, budget breach, provider failover, guardrail false-positive +triage. Admins are the reader most poorly served today. + +**Troubleshooting** — indexed by the symptom *as a reader would type it*, not by subsystem. +`` earns its place here: one per symptom, expanded on anchor link, so a support +engineer can send a deep link. + +--- + +## 6. What I would deliberately not do + +- **No dashboard screenshots as primary explanation.** They are the fastest-rotting asset on + the site and they orient nobody who has not already logged in. Diagrams for mechanism, + screenshots only for "click this specific thing". +- **No feature-per-page inventory as the top-level structure.** It reads as a price sheet and + serves the org chart rather than the reader. +- **No permanent marketing banner.** Spending the one attention slot on something evergreen + means it is unavailable when something urgent happens — which is exactly §10's withdrawal + scenario. +- **No custom React until a native component has been ruled out.** The handoff is explicit, and + the component inventory above shows there is a lot of unused native surface first. +- **No inherited prose, however good it looks.** Restating the rule because a redesign is + precisely when "we'll just restyle the existing pages" becomes tempting. + +## 7. Sequencing + +Cheap and independent of KB access — could ship this week: + +1. Colours (fix the light/dark defect), logo, fonts, favicon, theme choice. +2. `search.prompt`, `thumbnails`, `contextual.options`, `markdown.instructions`. +3. Retire the inherited banner; leave the slot empty. +4. The data-path diagram, light and dark. One asset, largest single effect. +5. Component rules written into the page contracts and enforced in review. + +Blocked on your skeleton: navigation primitive, tab count, home page composition. + +Blocked on KB access (Q2): every word of body copy on every page. + +Worth noting the ordering is deliberate — the visual identity work is entirely ungrounded-safe, +because none of it makes a product claim. It is the one substantial thing that can proceed at +full speed while authoring is blocked. + +## 8. Open questions for you + +1. ~~**Version or product?**~~ **Answered 2026-09-07 — stays a `versions[]` entry for now.** + Revisit before the first substantial batch of pages publishes, since the cost is a redirect + per published route. +2. **Brand latitude.** How closely must this track PANW brand — exact palette and type, or a + docs-appropriate interpretation? +3. **Is there a console sign-in URL** worth a navbar primary button at launch? +4. **Do security reviewers need PDF export?** `download-pdf` is one line, but it changes how + pages should be written — a page assuming hover states and live links reads badly on paper. +5. **Do the four readers above match how the product is actually sold?** I derived them from + the corpus and the RFP artifact, which is a sales document rather than a KB source, so this + is the assumption most likely to be wrong and cheapest to correct now. diff --git a/prisma-airs/_project/openapi-handoff.md b/prisma-airs/_project/openapi-handoff.md new file mode 100644 index 00000000..a5056700 --- /dev/null +++ b/prisma-airs/_project/openapi-handoff.md @@ -0,0 +1,291 @@ +# Handoff: the Prisma AIRS OpenAPI specification + +For the agent building the new OpenAPI repository. Answers Q6's source question; the grounding +question stays open and is described below. + +Context: `Portkey-AI/openapi` currently feeds this repo's API reference. It is Portkey-corpus +tooling. The new repository replaces it as the Prisma AIRS source. + +## Read this first + +**An OpenAPI specification is published documentation, not configuration.** + +219 pages in this repo render directly from the spec. Every `summary`, `description`, example +and enum note in it becomes public prose on the docs site and in `llms.txt` / `llms-full.txt`. +So handoff §3 rule 2 applies to the spec exactly as it applies to a hand-written page: every +substantive assertion needs accepted KB support. + +This is the easiest place in the whole corpus for grounding to lapse, because a spec does not +feel like writing. It feels like filling in fields. + +## The trap: do not fork and rebrand + +The obvious move is to clone `Portkey-AI/openapi`, rename things, and ship. That inherits every +ungrounded assertion in it, laundered through a new repository into a corpus that is supposed +to be re-grounded. + +Handoff §3 rule 7: published documentation is not corroboration of its own claims. The existing +spec's descriptions are published documentation. + +The line to hold — and this is the whole instruction in one sentence: + +> **Inherit the shape. Re-ground the prose.** + +| Carry over | Do not carry over | +|---|---| +| Paths and methods | `summary` | +| Schema structure, property names, types | `description`, at every level | +| `required` lists, enum *values* | Explanatory prose in examples | +| Status codes, error shapes | `info.description` | +| Security scheme definitions | Tag descriptions | +| Parameter names and locations | Any stated limit, default, or behaviour | + +The distinction is not arbitrary. Everything in the left column is **machine-verifiable against +the running API** — send a request, compare the response, and the claim is settled without the +KB. Everything in the right column is an assertion about behaviour that only the KB can +support. The left column can be inherited *and tested*. The right column cannot be inherited at +all. + +Where the KB does not yet support a description, **leave it empty**. An empty description +renders as a visible gap and shows up in coverage. A confident, plausible, wrong description is +invisible and will survive review. Empty beats invented, every time. + +## How the docs should consume it — do not repeat the current pattern + +Everything in this section was verified against the installed `mint` CLI **4.2.876** by reading +`@mintlify/validation` schemas and `@mintlify/common` / `@mintlify/scraping` type definitions. +Web access is blocked from this workspace, so it was not read from Mintlify's own +documentation — treat it as accurate for this CLI version and worth confirming against their +docs before relying on the finer points. + +### What this repo does today, and why not to copy it + +219 hand-written `.mdx` stub files, each one binding to a single operation by frontmatter: + +```yaml +--- +title: "Chat" +openapi: post /chat/completions +--- +``` + +Each is separately listed in `docs.json` navigation, and several carry a manually pasted +snippet import. Adding an endpoint means writing a file and editing navigation. This is the +"inefficient way" — it is 219 files of hand-maintained coupling. + +Consequence while it lasts: **method+path is the join key.** Renaming a path silently unbinds a +page — it still builds, it just stops rendering an operation. A path change is a docs migration, +not a spec edit. + +### What to build instead + +`groupSchema` accepts `openapi`, `asyncapi`, `tag`, `directory` and `expanded` alongside +`pages`. Putting `openapi` on a navigation **group** makes Mintlify generate a page per +operation: + +```json +{ + "group": "Endpoints", + "openapi": { + "source": "https://raw.githubusercontent.com///main/openapi.yaml", + "directory": "api-reference", + "overlays": ["overlays/docs-prose.yaml"] + } +} +``` + +No stub files, no per-endpoint navigation entries, no join key to keep in sync. `tag` on a +group filters operations into it, so tag structure in the spec becomes navigation structure. + +Only HTTPS sources are accepted; HTTP requires the CLI's `--local-schema` flag. + +### Overlays are the important find + +`openapi.overlays` takes **OpenAPI Overlay documents, applied in order**. From the schema's own +description: *"An empty array disables all overlays for this specification, including +auto-discovered ones"* — so Mintlify auto-discovers overlay files as well as honouring explicit +ones. + +This solves a problem the rest of this handoff could only work around. The spec can stay a +clean engineering artifact holding structure, while documentation prose lives in a **separate +overlay document** applied at build time: + +| Artifact | Owner | Content | Review | +|---|---|---|---| +| `openapi.yaml` | Engineering | Paths, schemas, types, required, enums, security | API review | +| `overlays/docs-prose.yaml` | Docs | `summary`, `description`, examples, tag prose | **Grounding gate** | + +That is *inherit the shape, re-ground the prose* expressed as two files instead of as a +discipline. The grounding gate applies to the overlay, which is small and entirely prose, and +engineering can ship structural changes without touching a single grounded assertion. + +Strong recommendation: adopt this split from the start. Retrofitting it means unpicking prose +from a spec that has already merged them. + +### `x-mint`, the vendor extension + +Operations and schemas accept an `x-mint` object. Verified fields: + +| Field | Effect | +|---|---| +| `metadata` | Page meta tags — becomes generated-page frontmatter | +| `content` | Extra MDX injected into the generated page | +| `pre` / `post` | MDX before and after the generated body | +| `href` | Override the generated page URL | +| `groups` | Assign the operation to navigation groups | +| `playground` | `{ expand }` — playground display | +| `mcp` | `{ enabled, name, description }` — expose the operation as an MCP tool | + +Also available: `x-hidden` and `x-excluded` on operations, and `x-mint-enum` on schemas for +enum display names. + +Two notes. `x-mint.content` / `pre` / `post` remove the last real reason to keep stub files — +per-endpoint custom prose no longer requires one. And `x-mint.mcp` is worth a deliberate +decision rather than a default, since it determines which operations become agent-callable +tools; that is a product surface, not a docs setting. + +Everything under `x-mint` that is prose is **published documentation** and inherits the +grounding rule. Prefer putting it in the overlay. + +## Naming rules + +[The naming rules](./README.md#naming-rules) applies, and its rule of thumb — *if a reader +would type it or a machine would parse it, it does not change* — resolves unusually cleanly +here, because a spec is mostly machine-parsed. + +**Never renamed:** + +- `servers[].url` — `api.portkey.ai` +- Header parameters — `x-portkey-api-key`, `x-portkey-provider`, every `x-portkey-*` +- `operationId` values +- Component and schema names +- Property names, enum values +- Security scheme keys + +**Rebranded:** + +- `info.title` → `Prisma AIRS AI Gateway API` +- `info.description` and every `description` / `summary` — subject to grounding, so rewrite + rather than translate +- Tag descriptions + +**Judgement call, flag rather than decide:** `tags[].name`. Tag names are simultaneously +display text (they drive navigation grouping) and reference keys (operations point at them). +Renaming affects both. Raise it rather than choosing. + +## Provenance: design the extension now + +The spec has to participate in the claim→section dependency index +([the provenance model](./README.md#provenance-model)), or 219 pages become a hole in it. Use +OpenAPI's `x-` extension mechanism, per operation and per documented property: + +```yaml +paths: + /chat/completions: + post: + summary: "" # empty until grounded + x-airs-provenance: + claims: + - id: "accepted-claim-id" + revision: "claim-revision-or-digest" + origin_kind: human # human|generated|mixed + text_digest: "sha256-of-the-description" +``` + +Add the field shape from the start even while `claims` is empty. This is the same argument as +the dependency index itself: it costs nothing while authoring and is prohibitively expensive to +retrofit, because reconstructing which claim supported a description after the fact is +indistinguishable from inventing it. + +`origin_kind` and `text_digest` are also what make echo protection work if any description is +ever machine-drafted. See [the reconciliation loop](./README.md#reconciliation-loop). + +## One spec, no variants + +Q12, 2026-09-07: launch covers managed and hybrid, and **product behaviour is +deployment-invariant.** Do not produce environment-variant specs or fork descriptions per +deployment. Multiple entries in `servers[]` are fine; divergent content is not. + +## Validation is currently absent — the new repo should own it + +Recorded because it contradicts an earlier entry in +[the platform facts table](./README.md#platform-facts), now corrected. + +`.github/workflows/openapi-validate.yml` in this repo runs +`openapi-spec-validator openapi.yaml` against the **docs-core repository root**, where no +`openapi.yaml` exists. `gh run list` shows no run history for the workflow at all. Meanwhile +`docs.json` reads the spec from +`raw.githubusercontent.com/Portkey-AI/openapi/refs/heads/master/openapi.yaml` — a completely +different artifact from the one CI names. + +So there is no working spec validation in this repository today. The new repo should validate +in its own CI, on its own file, and prove it with a run history rather than a workflow file. + +Note that `mint validate` in docs-core *does* fetch and check the remote spec — it reports +`OpenAPI definition is valid`. That is the real check today, and it lives on the docs side. + +## Authority: the spec is a second trusted source — recorded exemption + +**Decided 2026-09-07 (Q6).** The OpenAPI specification is a **key source of trusted knowledge +that sits outside the KB corpus.** It is not subordinate to the KB and is not merely an +ingestion input. + +This is a deliberate deviation from handoff §3 rule 1, which names the KB the *sole* factual +authority, and it is written here as the explicit recorded exemption that Q6 asked for. It is +scoped to the API specification. It does not weaken grounding anywhere else, and it must not be +cited as precedent for a second exemption. + +The operating rules: + +1. **Two trusted sources, one truth.** The spec and the KB are both authoritative in their + domains. Neither silently overrides the other. +2. **Conflicts are resolved by maintainers.** Never automatically, never last-write-wins. This + is the same principle §5 already applies to KB conflicts, extended to the spec. +3. **They must stay in sync, and drift from *either* side is raised.** Drift is a defect + regardless of which artifact moved. There is no "authoritative" side to fall back on. +4. **Sync is bidirectional and webhook-driven.** A spec change fires a webhook to the KB; a KB + change fires a webhook to the spec repository. + +### What this changes downstream + +[the reconciliation loop](./README.md#reconciliation-loop) was designed as a two-node loop, KB +↔ docs. It is now **three-node**: KB ↔ spec ↔ docs. Three consequences, recorded there: + +- Drift detection needs a KB↔spec comparison, not only KB↔docs. +- Webhooks on both sides give the loop real push triggers, so polling becomes the backstop + rather than the mechanism. +- A KB↔spec contradiction is a maintainer decision with no diff to review — structurally the + same as tier 3, and it inherits tier 3's handling. + +### What it means for this repository + +Keep populating `x-airs-provenance`. Its purpose shifts slightly but does not go away: it is no +longer only "which KB claim supports this description," it is also the **join key that makes +drift detectable**. Without a claim reference on an operation, nothing can tell that the KB +moved and the spec did not. + +## Still open + +**Q2, KB access.** Not yet available from the docs workspace, and the webhook contract in both +directions depends on it. Until then, description authoring is blocked exactly as page +authoring is. Structural work — paths, schemas, types, overlay split, provenance scaffolding, +CI — is unblocked and is the right thing to do first. + +## Suggested order + +1. Structure only. Paths, methods, schemas, types, required, enums, security. Verified against + the running API, not against the old spec. +2. CI that validates, with run history. +3. **Split prose into an overlay** from the first commit — `openapi.yaml` for structure, + `overlays/docs-prose.yaml` for everything a reader reads. Cheap now, painful later. +4. `x-airs-provenance` scaffolding on every operation, `claims` empty. +5. Naming pass over prose fields — titles and tag descriptions. Leave `description` empty + rather than porting. +6. Tag structure, deliberately: tags become navigation groups under the group-level `openapi` + config, so tag design is information architecture. +7. **Stop.** Descriptions wait for the KB. + +Steps 1–6 need no KB access and are worth doing now. Step 7 is where the handoff comes back. + +Two things to hand back rather than decide: the `tags[].name` question above, and which +operations should carry `x-mint.mcp` — that one is a product surface decision. diff --git a/prisma-airs/_project/prisma-airs-docs-mintlify-handoff-v2.md b/prisma-airs/_project/prisma-airs-docs-mintlify-handoff-v2.md new file mode 100644 index 00000000..05fac656 --- /dev/null +++ b/prisma-airs/_project/prisma-airs-docs-mintlify-handoff-v2.md @@ -0,0 +1,407 @@ +--- +title: "Prisma AIRS AI Gateway — Docs on Mintlify" +subtitle: "Implementation handoff: excellent product docs, connected to the KB" +version: "2.0" +status: "Ready for implementation; live KB contracts to verify" +date: "2026-09-07" +audience: "Docs implementation agent and documentation owners" +--- + +# Prisma AIRS AI Gateway — Docs on Mintlify {.unnumbered} + +> **IMPLEMENTER DIRECTIVE** +> Build excellent public product documentation for Prisma AIRS AI Gateway on Mintlify. Consume accepted public knowledge from the Prisma AIRS KB and contribute engineering-originated changes through its MCP server. Deliver INIT 1: usable, published documentation. Deliver INIT 2: continuous bidirectional reconciliation. Mintlify supplies the documentation platform. Do not build hosting, rendering, search, or preview infrastructure. Do not take responsibility for other products, shared namespaces, or collisions; the operator handles those concerns. + +## 0. Controlling decisions + +This version supersedes the infrastructure-heavy docs handoff v1. The scope is exclusively Prisma AIRS AI Gateway. This is a build brief, not an authored product corpus: it makes no claims about AI Gateway behavior that the implementation agent may publish without retrieving accepted KB support. + +Confirmed requirements: + +- Audience: public customers and developers. +- Platform: Mintlify, using its native experience, serving, and publishing facilities. +- Knowledge: the existing Prisma AIRS KB; no separate docs truth store. +- Eligibility: any accepted, public-approved KB knowledge that serves a relevant docs page. +- Authoring: engineering may originate knowledge in docs or the KB. +- Contributions: docs factual changes and engineering changelogs initiate KB proposals through MCP. +- Synchronization: both directions, with provenance, conflict handling, and recovery. +- Scope exclusions: other products, namespace coordination, product switching, and cross-product migration. +- Live KB verification is explicitly deferred to implementation; it does not block this handoff or local scaffolding. + +Recommended defaults, to distinguish from confirmed requirements: + +- Generate and validate proposals automatically; initially require human approval for public publication. +- Keep contradictions under the KB's existing human-review policy. +- Prefer durable repository revisions for detecting authored changes; use Mintlify publication status to verify public delivery. +- Reuse existing KB tasks, sandboxes, credentials, model routing, event handling, and scheduling where supported. +- Begin with English unless the operator specifies otherwise. + +MUST denotes a required boundary. SHOULD denotes a strong recommendation. DEFAULT denotes an implementation starting point. Record consequential deviations and ask the operator before changing knowledge authority, public approval, or MCP boundaries. + +## 1. Ownership + +| Owner | Responsibility | +|---|---| +| Mintlify | Documentation rendering, serving, native components, platform navigation, previews, and publishing facilities | +| Docs agent | Reader journeys, information architecture, page composition, examples, editorial quality, configuration, and documentation validation | +| KB | Claims, evidence, authority, acceptance, public scope, freshness, and contradiction resolution | +| Integration tasks | Change detection, dependency tracking, MCP submissions, review tracking, reconciliation, and audit | +| Operator | Access, publication owners, supplied placement in Mintlify, and operational choices outside this product scope | + +Mintlify owns the platform mechanism; the docs agent still configures the experience and verifies that the resulting pages work. Platform delegation does not delegate factual accuracy or knowledge acceptance. + +The earlier requirement to deploy the docs surface entirely on GCP is superseded by the Mintlify decision. Any small custom integration should first reuse the existing KB infrastructure. Do not introduce another cloud deployment merely because v1 listed one. + +## 2. Model — documentation designed around reader tasks + +The Model plane describes pages, reader journeys, navigation, examples, dependencies, and editorial ownership. Canon, Practice, and Pulse remain KB freshness metadata, not mandatory public navigation. + +### Reader journeys + +Build a coverage map for these journeys, adjusting page labels to the verified product: + +1. Understand what the gateway does and when to use it. +2. Complete a first successful integration. +3. Configure a supported capability for a concrete task. +4. Operate and troubleshoot the integration. +5. Look up an exact contract, parameter, error, or limitation. +6. Understand a shipped change and any required action. + +Do not assume the product has a feature because a familiar gateway does. Missing KB support becomes a knowledge-gap task, not plausible filler. + +### Page contracts + +| Page type | Required content contract | +|---|---| +| Overview/concept | Purpose, mechanism, boundaries, applicability, next useful task | +| Quickstart | Prerequisites, minimal steps, complete working example, expected result, verification, next step | +| How-to guide | One goal, environment/version, steps, checks, failure cases | +| API/reference | Exact versioned contract, parameters, types, defaults, errors, examples | +| Operations | Procedure, prerequisites, verification, recovery/rollback where applicable | +| Troubleshooting | Recognizable symptom, diagnostic steps, supported causes and remedies | +| Changelog | Release identity/date, applicability, what changed, migration impact | +| Example | Dependencies, complete runnable code, expected behavior, supported version | + +### Writing and experience requirements + +- Lead with the reader's goal and the shortest useful answer. +- Keep concepts separate from procedures and reference details; connect them with purposeful links. +- Make prerequisites and environment assumptions explicit before commands. +- Use copyable, complete examples with safe placeholders; never include real credentials. +- Explain how the reader knows a step worked. +- Prefer native Mintlify components; use custom presentation only for a specific reader need. +- Use callouts for actionable constraints, not decoration. +- Keep language precise, direct, and consistent with a controlled product vocabulary. +- Make headings, navigation labels, and page descriptions specific enough to support discovery. +- Avoid internal KB terminology in the public reading flow unless it helps the customer. +- Validate mobile layouts, keyboard navigation, links, code presentation, and relevant search behavior through Mintlify's actual output. + +### Identity and provenance + +Every page requires a stable ID, assigned route, page type, owner, applicability, lifecycle state, and source revision. Track claims at section/assertion granularity. A change to one fact should not rewrite unrelated editorial work. + +Illustrative private manifest; adapt to actual KB identifiers: + +```yaml +schema: docs.page.v2 +page_id: docs.ai-gateway.example-guide +route: "operator-assigned-page-route" +type: guide +owner: "docs-owner" +applies_to: "explicit-supported-version-or-environment" +docs_revision: "git-sha" +kb_revision: "immutable-kb-revision" +sections: + - id: example-section + assertions: + - id: assertion-1 + claim_refs: + - id: "accepted-claim-id" + revision: "claim-revision-or-digest" + generated_by: "task-id" + reviewed_by: "review-reference" +publication: + build_id: "publication-id" + policy_revision: "policy-revision" +``` + +Keep operational manifests private and outside Mintlify's public exports. A page absent from navigation is not necessarily private. Do not rely on navigation omission to protect evidence, review notes, or internal IDs. + +Maintain a rebuildable claim-to-section dependency index and an eligible-knowledge coverage ledger. Each eligible claim is used, awaiting placement, blocked, or intentionally omitted with a reason. Eligibility does not require one page per claim. + +## 3. Knowledge boundary — supplied by the KB + +The docs system may store prose and editorial structure. It does not independently accept product facts. + +Required rules: + +1. All KB reads and writes use its approved MCP interface. No direct corpus Git, index, database, or evidence bucket access. +2. Every substantive published assertion must have applicable accepted KB support. This includes numbers, defaults, limits, instructions, prerequisites, code assumptions, and claimed outputs. +3. Claim ID existence is insufficient: the cited claims must support the assertion's actual meaning and scope. +4. Recheck public eligibility and current claim status before publication, not only at generation time. +5. No invented content to fill gaps. Record a blocked section or contribute a source through MCP. +6. Public rendering, search, downloads, examples, metadata, and enabled machine-readable exports must exclude private material. +7. Generated documentation cannot become independent corroboration of its own source claims. +8. KB acceptance and docs publication are separate state transitions. + +Visible source citations are an editorial choice; full private provenance is mandatory. Non-substantive headings and connective prose do not need claim IDs. Code execution tests complement factual support; they do not establish unrestricted product guarantees. + +## 4. Tasks — the docs agent's actual work + +| Task | Input | Reviewable output | +|---|---|---| +| Plan coverage | Reader journeys and public KB inventory | Navigation/page map and knowledge gaps | +| Compose page | Page contract and accepted KB slice | MDX proposal and assertion manifest | +| Update affected sections | Changed claim revisions and dependency map | Minimal patch preserving editorial work | +| Improve reader experience | Review findings and permitted feedback | Navigation, prose, example, or layout proposal | +| Contribute factual edit | Engineering-authored semantic delta | KB MCP task handle and tracked disposition | +| Process release | Authorized changelog/release observation | KB contribution and impacted-page proposals | +| Validate publication | Proposed revision and current KB policy | Gate report and publication readiness | +| Reconcile | KB revisions, docs revisions, publication status | Applied/no-op/conflict/blocked/failed ledger | + +Use the KB's task and sandbox system where it supports these operations. The docs agent should receive a public-approved slice and an output workspace. It must not gain unrestricted internal knowledge simply because its output will later be filtered. + +### KB → docs + +1. Receive an accepted-change event or discover a revision difference through reconciliation. +2. Obtain authoritative claim state through MCP and evaluate eligibility. +3. Find affected sections and evaluate placement for new eligible claims. +4. Pin KB and docs base revisions; produce a scoped MDX/configuration patch. +5. Validate support, scope, applicability, examples, links, and Mintlify rendering. +6. Open a reviewable proposal and follow publication policy. +7. Recheck base revisions and public eligibility before publishing. +8. Confirm Mintlify publication success and record the public revision. + +### Docs → KB + +1. Observe a durable, review-ready authored revision or an engineering release event. +2. Compare against the common base and classify editorial, factual, generated, or mixed changes. +3. Submit original factual deltas and provenance through MCP automatically. +4. Track the handle through acceptance, rejection, or conflict. +5. Reconcile affected docs after acceptance; preserve a visible review case otherwise. + +Avoid submissions on every keystroke. Editorial-only changes need no factual mutation or freshness update. Human edits of generated text must retain generated ancestry while contributing the new factual delta. + +### Engineering changelogs + +Docs-native engineering changelogs can originate new knowledge: author the release entry, automatically submit its facts through MCP, and publish under the agreed gates after acceptance. + +An already-published engineering release is an observation to ingest, not proof of prior KB acceptance. Preserve release ID, author, date, applicability, source revision, digest, and correction history. Use it to propose current guide/reference updates without silently rewriting the historical release. + +DEFAULT: normal docs publication waits for KB acceptance. If the operator wants docs-native releases to publish first, encode that as an explicit release-only policy exception; it must not silently weaken grounding for all pages. + +## 5. Minimal integration — continuous reconciliation + +Mintlify publishing does not itself establish semantic synchronization with the KB. Retain only the integration machinery needed for dependable effects, preferably inside existing KB task facilities. + +| Mechanism | Purpose | +|---|---| +| Authenticated events | Promptly identify durable changes | +| Private dependency manifests | Locate affected pages and sections | +| Task/disposition ledger | Track contributions, proposals, retries, and review | +| Provenance and content digests | Distinguish originals, generated echoes, and mixed edits | +| Revision checks | Prevent overwriting newer human work | +| Periodic reconciliation | Recover missed events and incomplete runs | + +Prefer repository events for authored revisions and Mintlify status for publication confirmation. A successful commit is not proof that readers received the update. Verify actual event/API availability before selecting adapters; do not invent a Mintlify outbound webhook. + +If KB events are unavailable, use approved MCP revision enumeration or snapshot/diff polling. If neither exists, record the missing capability for the KB owner. Never bypass MCP to create a change feed. + +### Proposed event fields + +```json +{ + "event_id": "unique-id", + "origin": "kb|docs|engineering-release", + "origin_kind": "human|generated|mixed", + "actor": "authenticated-principal", + "correlation_id": "logical-change-id", + "causation_id": "preceding-event-or-null", + "base_revision": "common-base", + "revision": "immutable-revision", + "affected_ids": ["page-or-claim-id"], + "content_digest": "sha256", + "generated_from": ["claim-revision"], + "occurred_at": "timestamp" +} +``` + +This is an illustrative contract. Authenticate the source; origin fields cannot grant authority. Persist receipt before acknowledgment. Use idempotency keys and conditional side effects so duplicate delivery creates one logical contribution, proposal, or publication. + +### Loop and conflict rules + +| Case | Required disposition | +|---|---| +| Unchanged generated docs return through ingestion | Echo/no-op; no new evidence or verification bump | +| Human changes generated factual prose | Submit the semantic delta with ancestry preserved | +| Formatting/spelling-only edit | Editorial change; no factual KB update | +| KB changes; docs facts unchanged | Propose affected-section update | +| Both sides change compatibly | Reconcile references and preserve editorial work | +| Both sides change incompatibly | Named review; no last-write-wins overwrite | +| Page deleted | Remove publication/dependencies, not KB knowledge | +| Public permission revoked | Urgent withdrawal under approved policy | +| Old event arrives late | Stale/historical disposition; no freshness rollback | + +The existing docs-ingestion pipeline must preserve generated ancestry too. Otherwise recrawling public Mintlify pages could undo loop protection. Treat this as an integration acceptance requirement. + +Every change ends as applied, no-op, excluded, pending review, conflict, blocked, or failed. Reconciliation compares KB state, source revisions, dependency manifests, and publication status; an empty queue is not sufficient evidence of synchronization. + +## 6. Mintlify configuration and resources + +Use the operator-provided Mintlify workspace, repository, and assigned product scope. The agent should configure the permitted documentation surface and native components, not solve placement outside it. + +Required resources are access and capabilities, not new infrastructure deployments: + +- Mintlify project/repository access and the assigned edit scope. +- Native MDX/component and navigation configuration. +- Existing preview, review, build, and publishing workflow. +- Authenticated KB MCP service identity with appropriate public-read and contribution permissions. +- Existing execution/harness/model routing for docs tasks, where available. +- Private provenance/dependency storage and durable sync state through existing facilities. +- Engineering source registrations and reviewer ownership. +- Existing event/scheduler facilities and operational visibility for the small integration. + +Do not build a custom frontend, search engine, hosting stack, CDN, preview service, or broad Terraform deployment for docs. If a native feature falls short, describe the reader problem and propose the smallest remedy before adding custom machinery. + +### Implementation-stage capability checks + +Verify MCP authentication, stable claim/revision reads, public approval/status fields, pagination/change discovery, contribution format, task status, grounding facilities, and provenance preservation. Map logical operations to actual tool variants; earlier brief examples are not evidence of deployed endpoints. + +Verify the supplied Mintlify workflow: allowed files, configuration ownership, local/branch preview, required checks, publication authority, and deployment-status observation. The current brief does not claim authenticated inspection of either live system. + +Proceed with page contracts, editorial standards, and local structure while access is pending. Do not claim integrated success until a real authorized read/contribution/publication round trip is demonstrated. + +## 7. Publication quality gates + +Before publication, require: + +1. Valid page and manifest schemas, stable IDs, assigned routes, and ownership. +2. Accepted, applicable support for every substantive assertion, with semantic support assessment. +3. Current public eligibility, including changed permissions after proposal creation. +4. No private data in public artifacts, metadata, enabled exports, or build outputs exposed by Mintlify. +5. Supported example assumptions, syntax checks, and appropriate runnable tests. +6. Working links/anchors and coherent next steps. +7. Mintlify preview review for desktop/mobile, keyboard navigation, code blocks, and page-specific layouts. +8. Base-revision checks protecting concurrent human edits. +9. Required editorial approval and verified public deployment status. + +Use dedicated approved test accounts for external API examples with bounded cost. Do not perform destructive or customer-state tests. If credentials are unavailable, distinguish static validation from a live execution test. + +Model evaluation is fallible. Keep reviewed golden cases for unsupported numbers, omitted conditions, stronger certainty, wrong citations, and version mismatch. A human approval does not waive deterministic scope or security failures. + +## 8. INIT 1 — excellent AI Gateway docs on Mintlify + +### Objective + +Deliver a usable, grounded first publication with an effective reader experience. Content is obtained from the KB during implementation; this brief defines the process and quality bar, not feature descriptions. + +### Sequence + +1. Inspect supplied Mintlify and KB access; record verified capabilities and missing integrations. +2. Map supported reader journeys and eligible knowledge; create a coverage and gap register. +3. Define page contracts, writing conventions, IDs, dependency manifests, and publication rules. +4. Configure navigation and native components within the assigned scope. +5. Build a representative vertical slice: a quickstart, concept, guide, reference, troubleshooting page, and release example where KB support exists. +6. Validate customer tasks, factual support, examples, links, and actual Mintlify rendering. +7. Implement a review-triggered contribution path for an engineering factual draft through MCP. +8. Expand approved coverage, publish through Mintlify, and demonstrate publication recovery using supported workflows. + +Missing knowledge should produce a contribution or research request to the KB. Do not turn INIT 1 into a parallel bulk source-ingestion project or copy unsupported source prose directly into public pages. + +### Exit criteria + +- [ ] Published AI Gateway docs serve agreed reader journeys within the supplied Mintlify scope. +- [ ] A representative first-use journey succeeds with the documented prerequisites and steps. +- [ ] Every substantive published assertion has applicable accepted KB support. +- [ ] Navigation, links, code presentation, mobile experience, and applicable discovery behavior are validated. +- [ ] Private provenance and section dependencies are complete and recoverable. +- [ ] An engineering factual draft can submit through MCP and track to a KB disposition. +- [ ] Publication status is verified, not inferred from a repository merge. +- [ ] Knowledge gaps and any unexecuted live tests are explicitly recorded. +- [ ] No custom docs-serving infrastructure was introduced. + +## 9. INIT 2 — bidirectional synchronization + +### Sequence + +1. Run shadow impact analysis: receive events and calculate expected effects without automatic publication. +2. Enable a small KB-to-docs canary; generate minimal section proposals and review their fidelity. +3. Enable engineering-originated docs contributions, including a changelog, editorial-only change, and human edit of generated text. +4. Add periodic reconciliation, durable retry, conflict routing, and missed-event recovery. +5. Verify generated ancestry survives the existing docs-ingestion connector. +6. Run replay, fault, conflict, scope, and publication tests. +7. Expand coverage and approve operating cadence, owners, budgets, and escalation. + +DEFAULT: retain human publication review. Auto-publication is a later, explicit choice for narrowly defined change classes after measured quality; contradictions must not be silently auto-resolved. + +### Exit criteria + +- [ ] KB changes reach every affected section or have explicit dispositions. +- [ ] New eligible knowledge without dependencies is evaluated for placement. +- [ ] Engineering facts/releases enter KB through MCP and track to acceptance, rejection, or conflict. +- [ ] Generated echoes create no independent evidence or verification refresh. +- [ ] Mixed edits preserve ancestry and contribute only original semantic changes. +- [ ] Duplicate, out-of-order, and missed events converge safely. +- [ ] Conflicting human and KB changes preserve both revisions for review. +- [ ] Withdrawal and publication recovery recheck current public eligibility. +- [ ] Reconciliation accounts for proposals, accepted revisions, and actually published revisions separately. +- [ ] Owners can diagnose stalled synchronization without inspecting agent conversations. + +## 10. Verification and operations + +| Test | Required result | +|---|---| +| One claim affects several pages | Every dependent section updates; unrelated editorial text survives | +| New claim has no page | Coverage evaluation and placement/omission recorded | +| Permission revoked while draft waits | Publication blocked by current-policy check | +| Generated docs recrawled | No false corroboration or repeating task chain | +| Engineer changes a generated sentence | Original delta submitted with provenance | +| KB rejects correction | Review case remains visible; unsupported draft does not publish | +| Release changes current behavior | Historical release preserved; current guides updated through accepted claims | +| Duplicate event or crash after side effect | One logical contribution/proposal/publication | +| Human edit during generation | Revision check prevents overwrite | +| Missing webhook | Reconciliation discovers and processes the gap | +| Valid citation with unsupported meaning | Grounding gate rejects or narrows assertion | +| Publication fails after merge | Ledger reports failure/pending delivery, not success | +| Rollback points to now-restricted claims | Revalidation blocks unsafe restoration | + +Track event-to-proposal time, KB acceptance time, human-review time, publication lag, conflicts, stale dependencies, knowledge gaps, failures, and task cost separately. Reuse existing observability facilities. + +Runbooks must cover KB unavailability, failed contribution handles, missed events, conflicts, failed Mintlify publication, rejected grounding, public-scope withdrawal, and replay/recovery. Scope withdrawal needs an approved urgent procedure using available Mintlify controls; do not leave it behind ordinary editorial review. Record any limitations on cache/export removal rather than promising deletion from third-party copies. + +## 11. Operational questions and implementation handoff + +Ask only what remains needed after inspecting configured access: + +- Which Mintlify project/repository and files constitute the assigned AI Gateway scope? +- What are the live KB MCP contract, service identity, and event/reconciliation capabilities? +- Who owns factual review, editorial publication, conflicts, and urgent withdrawal? +- What authoritative engineering specifications and release inputs are registered with the KB? +- Which supported versions, environments, languages, and reader journeys are launch-critical? +- What publication policy applies to engineering changelogs that originate in docs? +- Which existing task/scheduler facilities, budgets, and notifications should the integration reuse? + +Do not ask the operator to reconsider Mintlify, public audience, KB authority, two-way authoring, namespace placement, or other products. Do not ask for secrets in chat; use normal configured access. + +Required deliverables: + +1. Reader-journey map, navigation, page contracts, and coverage/gap register. +2. AI Gateway MDX/configuration changes within the supplied Mintlify scope. +3. Private provenance manifests and claim-to-section dependency model. +4. MCP consumer/contributor integration and minimal reconciliation tasks. +5. Grounding, examples, rendering, and publication validation evidence. +6. INIT 1 and INIT 2 exit reports, operating notes, and unresolved limitations. + +Start by proving one relationship end to end: retrieve accepted public KB knowledge, create a grounded Mintlify page proposal, receive a human factual change, contribute it through MCP, and reconcile the accepted result. Scale coverage after that path is trustworthy. + +## 12. Platform references and change record + +Use current official Mintlify documentation for configuration syntax and workflow details. The pages below were checked during the design discussion; re-check them during implementation rather than treating their behavior as a deployed-project guarantee. + +- [Navigation and page organization](https://www.mintlify.com/docs/organize/navigation) +- [GitHub repository integration](https://www.mintlify.com/docs/deploy/github) +- [Publishing and review workflow](https://www.mintlify.com/docs/editor/publish) + +Version 2 removes the custom docs platform build, cross-product/namespace work, migration assumptions, and broad infrastructure provisioning from version 1. It retains reader-oriented modeling, KB-only knowledge authority, grounding, original engineering contributions, provenance, and bidirectional reconciliation. + +The assignment is excellent Prisma AIRS AI Gateway documentation on Mintlify. All engineering choices should be assessed against that outcome. diff --git a/prisma-airs/overview.mdx b/prisma-airs/overview.mdx new file mode 100644 index 00000000..6ac724c6 --- /dev/null +++ b/prisma-airs/overview.mdx @@ -0,0 +1,65 @@ +--- +title: "Prisma AIRS AI Gateway" +description: "Documentation for Prisma AIRS AI Gateway." +sidebarTitle: "Overview" +--- + +{/* + GROUNDING STATUS: scaffold. + + This page carries no product capability claims. It is navigation and branding only, + which is why it can exist before Prisma AIRS KB access is established. + + Do NOT add capability, limit, default, or behavior statements to this page until every + such assertion has accepted KB support and a manifest entry. + See prisma-airs/_project/README.md. + + No prisma-airs-cta snippet here, by decision (2026-09-07): that CTA announces the Portkey -> + Prisma AIRS transition to readers of the Portkey-branded docs. It is redundant on pages that + are already Prisma AIRS. Do not add it to pages in this version. +*/} + +Prisma AIRS AI Gateway is the AI gateway from [Palo Alto Networks](https://www.paloaltonetworks.com). + + + This documentation version is being built out. Pages appear here as they are completed. + For the full current documentation set, switch to the **Latest** version using the + version selector. + + +## Current documentation + +Complete documentation for every capability is available in the **Latest** version while +these pages are migrated. + + + + Make your first request through the gateway. + + + Routing, fallbacks, retries, caching, and load balancing. + + + Provider integrations, budgets, and rate limits. + + + Input and output checks, PII redaction. + + + Logs, traces, analytics, and OpenTelemetry. + + + Gateway and Admin API contracts. + + + +## Deployment + + + + Deploy the data plane in your own cloud. + + + Management plane architecture. + + diff --git a/product/mcp-gateway/authentication/index.mdx b/product/mcp-gateway/authentication.mdx similarity index 100% rename from product/mcp-gateway/authentication/index.mdx rename to product/mcp-gateway/authentication.mdx