docs(prisma-airs): kickstart the Prisma AIRS AI Gateway documentation project - #1065
Open
vrv-panw wants to merge 14 commits into
Open
docs(prisma-airs): kickstart the Prisma AIRS AI Gateway documentation project#1065vrv-panw wants to merge 14 commits into
vrv-panw wants to merge 14 commits into
Conversation
Kickstarts the Prisma AIRS AI Gateway documentation initiative described in
the v2 Mintlify handoff.
Scope confirmed: the whole corpus is Prisma AIRS AI Gateway, rebranded in
place. Other tabs are modules of it, not separate products.
Migration runs through a third navigation.versions[] entry, "Prisma AIRS",
inserted between "Latest" and "Virtual Keys (Deprecated)". "Latest" stays
first and therefore stays the default version. Pages join the new version
one at a time, only after passing the grounding gate; its page count is the
INIT 1 progress metric.
prisma-airs/overview.mdx is a scaffold carrying no product capability claims
-- navigation and branding only, which is the only kind of page writable
before Prisma AIRS KB access exists. Its grounding status and publication
gate are recorded in an MDX comment on the page itself.
Planning artifacts under prisma-airs/_project/ (.md, not built by Mintlify):
- 00-capability-register verified vs pending access; records that KB MCP
access is absent, which blocks all page authoring
under handoff section 3 rule 2
- 01-reader-journeys six journeys mapped to real routes, gap register,
proposed vertical slice
- 02-page-contracts eight page types bound to this repo's components
and writing-style-guide.md
- 03-provenance-model manifest schema, dependency index, coverage and
disposition ledgers, corpus bootstrap approach
- 04-operator-questions twelve open questions, only those the repo could
not answer
- 05-naming-rules Portkey -> Prisma AIRS vocabulary rule; functional
identifiers (portkey_ai, PORTKEY_*, x-portkey-*,
api.portkey.ai) explicitly never rename
- 06-changelog-contribution-path the docs->KB MCP round trip, piloted on
release changelogs
Not verified: mint is not installed locally and network egress is blocked
here, so docs.json was validated as JSON and the page path confirmed to
resolve, but the version selector has not been rendered.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two additions to the update-changelog skill that the Prisma AIRS handoff
requires and that need no KB access to build.
Step 4a -- extract factual assertions. Before writing prose, the discrete
facts a release establishes go to a YAML file under
prisma-airs/_project/releases/. One assertion per fact rather than per PR,
stating the fact itself ("default request timeout is 60s") rather than the
edit ("updated the timeout section").
The supersedes field carries the weight. Net-new capabilities are easy; the
expensive case is a release that quietly changes a documented default,
because nothing in the release notes flags that a guide is now wrong.
supersedes plus affects records that, and is the manual stand-in for the
claim-to-section dependency index. Note also that kind: fix normally has an
empty supersedes -- a fix restores documented behavior. A "fix" that changes
documented behavior is a behavior-change, and mislabelling it hides the
staleness.
Step 7 -- split into two outputs on two clocks, in separate commits. The
changelog entry is immutable once published; guides are not. A release entry
is a dated observation that stays true forever, even after the behavior it
describes changes again, so rewriting it to match a current guide destroys
the record of what a customer running that version actually got. Three new
pitfalls enforce the boundary.
Step 8 now reports assertion counts by kind and, separately, every assertion
with a non-empty supersedes -- those are the ones that silently invalidated
a page.
No backfill of existing changelog entries: reconstructing assertions from
published prose would violate handoff section 3 rule 7, which forbids
treating documentation as evidence for its own claims. Both changes take
effect on the next release, and are untested until one runs.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
mint validate (now installed locally) raised a parse error inside prisma-airs/_project/prisma-airs-docs-mintlify-handoff-v2.md -- a file no docs.json navigation entry references. The scaffold commit asserted that planning artifacts were safe because they are .md rather than .mdx and are absent from navigation. Both halves of that are wrong: Mintlify processes .md as well as .mdx, and navigation omission does not exclude a file from the build or from the public exports (llms.txt / llms-full.txt). This is precisely the trap handoff section 2 warns about -- "A page absent from navigation is not necessarily private. Do not rely on navigation omission to protect evidence, review notes, or internal IDs." The actual mechanism is a repo-root .mintignore, gitignore syntax, which this adds for prisma-airs/_project/. Mintlify additionally always ignores .git, .github, .claude, .agents, .idea, node_modules and README.md -- which is why the .claude skill changes and the _project READMEs raised nothing. Corrects the claim where it was made, in _project/README.md, 03-provenance-model.md and releases/README.md, and records the verified platform capabilities in 00-capability-register.md. Also flags, without changing, that writing-style-guide.md, MCP-Gateway-Roadmap.md, create-split-prs.sh and two stray root images are inside the build scope for the same reason. They parse cleanly so they warn about nothing, but excluding them would change existing published output and is outside this scope. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Decisions taken 2026-09-07, recorded in 04-operator-questions.md and reflected in the documents they govern: - Q3 naming rule approved as proposed, including the four items 05-naming-rules.md had flagged as unresolved (OSS Gateway identity, community CTAs, status.portkey.ai, and the compliance and uptime claims on the entry page). - Q7 owners: Vrushank Vyas owns factual review, editorial publication, conflicts and urgent withdrawal. - Q8 "Virtual Keys (Deprecated)" version: keep as is. - Q9 changelog publication: release-only exception approved. Entries publish on the release schedule; guide and reference patches wait for KB acceptance. 06-changelog-contribution-path.md now states this as operating policy rather than as a recommendation. Answered questions are annotated in place rather than deleted -- the reasoning is why the answer means what it means, and it is worth keeping next to the decision. Standing instruction also recorded: do not modify non-Prisma-AIRS docs. Pre-existing broken links and root-level non-page files are accepted as-is. Removes the prisma-airs-cta snippet from overview.mdx. 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. The page comment now carries that as a standing rule for the version. Q2 (KB MCP endpoint) remains the only blocker on page authoring. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Adds 07-reconciliation-loop.md, the INIT 2 companion to the changelog contribution path. Where 06 covers docs->KB on one page type, this covers the standing loop in both directions across the migrated corpus. The loop is a divergence detector that opens pull requests, not a self-updating docs set: handoff rule 7 means an agent that both authors and accepts a claim has closed a loop with no external truth in it. Records the four-tier triage model, the dependency index as the real precondition, ledger transitions, and echo contamination as the failure mode that is invisible from inside the loop. Adds Q13 (cursor-based vs snapshot-only KB change discovery), which has to be answered before the KB->docs watcher can be designed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Q5 is moot and generalizes: defects in the Portkey-branded corpus are out of scope entirely, since Prisma AIRS pages are produced by re-grounding rather than by inheriting and correcting existing prose. Q6 assigns Prisma AIRS API reference to a new OpenAPI repository, not yet supplied. The grounding status of that spec -- ingested or exempted -- stays open and is flagged where it bites. Q12 establishes deployment invariance: managed and hybrid behave the same, so applies_to carries version applicability only. No environment-variant page sets, no per-environment claim fan-out, one-dimensional coverage ledger. Launch scope and skeleton reserved to the operator. Q13 downgraded from prerequisite to performance detail. The previous snapshot already exists as claim_revision_seen, so reconciliation runs against the manifests regardless of contract shape; a cursor only narrows which claims to re-read, and is never the source of truth. Q11 confirmed a hard prerequisite, with the requirement sharpened from preserving generated ancestry to refusing it as corroborating evidence. Q10 proposal recorded: Actions cron, three per-run ceilings, GitHub issues as the tier-3 record. Flags the single-owner review queue as the item that actually needs solving before the loop runs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…esign Tier 1 and tier 2 events are ordinary pull requests -- the body quotes the claims and the diff is one value, so verification is a string comparison, not a factual-authority judgement. Any maintainer reviews them, and the repo already sustains roughly eight distinct reviewers across recent merges with no bottleneck and no CODEOWNERS. The earlier draft carried Q7's migration-authority assignment into the loop, where it does not apply. Keeps the mistake visible rather than deleting it, since the reasoning is easy to repeat. What survives is narrower and is workflow config: tier 3 emits an issue rather than a PR, and issues have no forcing function, so the open item is the default assignee at creation time. Separately, a PR queue cannot report that the loop stopped opening PRs -- so the loop opens an issue about itself when its own health check fails, rather than assuming anyone reads a dashboard. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
An OpenAPI spec is published documentation, not configuration: 219 pages render from it and every description reaches llms-full.txt, so rule 2 applies to it as it does to a hand-written page. The handoff leads with that because a spec does not feel like writing, it feels like filling in fields. Central instruction is inherit the shape, re-ground the prose. Structure is machine-verifiable against the running API and can be carried over and tested; descriptions are behavioural assertions only the KB can support and cannot be carried over at all. Where the KB is silent, leave the field empty -- an empty description is a visible gap, an invented one survives review. Also records that method+path is the join key between spec and docs, so a path rename is a docs migration rather than a spec edit. Corrects 00-capability-register: openapi-validate.yml was cited as evidence of a verified capability, but it validates openapi.yaml at the docs-core root where no such file exists, has no run history, and names a different artifact from the remote spec docs.json actually reads. There is no working spec validation here today. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ource Mintlify mechanics verified against the installed CLI 4.2.876 by reading @mintlify/validation schemas and @mintlify/common type definitions. Web access is blocked from this workspace, so this is not sourced from Mintlify's own docs and the finer points are worth confirming. The current pattern -- 219 hand-written stub files each binding one operation by method+path frontmatter, each listed in navigation -- is replaced by group-level openapi config, which generates a page per operation with no stubs and no join key to maintain. The significant find is openapi.overlays: OpenAPI Overlay documents applied in order, auto-discovered as well as explicit. That turns "inherit the shape, re-ground the prose" from a discipline into two files -- structure in the spec under API review, prose in an overlay under the grounding gate. Recommended from the first commit; retrofitting means unpicking merged prose. Also records the verified x-mint surface (content, pre/post, href, groups, playground, mcp) and x-hidden / x-excluded / x-mint-enum. Q6 grounding status settled as a recorded exemption: the spec is a second trusted source outside the KB corpus, co-equal rather than subordinate. Written up as a deliberate, scoped deviation from rule 1 so it cannot later be cited as precedent. Conflicts to maintainers, drift raised from either side, bidirectional webhooks. That makes the reconciliation loop three-node. Drift is symmetric with no authoritative fallback, KB-spec contradictions inherit tier 3 handling, and webhooks become the latency path while scheduled reconciliation stays the truth path -- a missed delivery is as silent as a missed cursor event. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Eight items from implementing INIT 1's unblocked envelope against the v2
brief, ordered by cost incurred rather than abstract severity.
The three that matter most: section 2's privacy hedge ("not necessarily
private") caused the exact failure it warns about, because navigation
omission provides no exclusion at all rather than partial exclusion; "sole
factual authority" did not survive contact with a second trusted source and
should become a trusted source register; and preserving generated ancestry
is not the requirement, refusing it at ingestion is -- as written, an
implementer can satisfy both stated requirements and still build a system
that silently corroborates itself.
Also records the missing platform-capability step, which caused the
structure/prose split to be designed as a discipline before discovering
Mintlify implements it natively via overlays, and the absent
existing-corpus disposition section, which blocked everything until the
operator ruled re-ground rather than inherit.
Closes with what held up, so v3 does not lose it while fixing the rest.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ten planning documents restated the same facts — rule 7 appeared in six, build exclusion in four, deployment invariance in three. Collapse 00-07 and 09 into a single deduplicated README where each fact is stated once, and drop the artifacts that were only versions of other artifacts. Removed: the .html render of the v2 brief (identical content), the PR body draft (not a repo artifact), and releases/README.md (its conventions are now the assertion-file section of the canonical doc; the directory is recreated on first write). Kept separate: openapi-handoff.md, because it is handed to a different agent building a different repository, and the v2 brief, because every decision here cites its section numbers. Dropped rather than folded: the per-journey route inventories in 01-reader-journeys. Launch scope and the navigation skeleton are reserved to the operator, which supersedes them. The gap register survives. Repointed the links in openapi-handoff.md, overview.mdx and the update-changelog skill. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
docs.json references "product/mcp-gateway/authentication", but that path is a directory whose landing page is index.mdx. Mintlify does not resolve a directory to its index, so the entry pointed at nothing and mint validate failed the whole build on it. Pre-existing on main and unrelated to the Prisma AIRS work, but kept as its own commit so the rename is reviewable on its own. Fixed by following the convention CLAUDE.md already states, "Index pages for sections are named after the section: observability.mdx (not index.mdx)", which product/ai-gateway.mdx and product/observability.mdx both follow. This was the only index.mdx in the repo. Renaming it leaves docs.json untouched. mint validate now passes with no warnings. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Design brainstorm for how the docs should present to developers, admins, security owners and evaluators — plus a self-contained HTML wireframe of six page archetypes with a light/dark toggle. Scoped to presentation, since the navigation skeleton is reserved to the operator. Where structure appears it is a worked example to react to. Grounded in the installed mint CLI 4.2.876 schema and the current docs.json rather than in Mintlify's site, which is unreachable from this workspace. Notable findings: colors.primary/light/dark are all set to the same hex, so neither mode gets a contrast-adapted accent; markdown. instructions is unset and is the natural place to state the naming rule for agent-facing pages; navigation accepts products/anchors/dropdowns as alternatives to the versions[] entry Prisma AIRS currently occupies. Component census across the corpus: 3005 Cards, 707 Tabs against 611 CodeGroups, and 48 Checks — the last being the tell that quickstarts are skipping the verification step the page contract requires. No product capability claims. Every label in the wireframe is a placeholder and the accent colour stands in for the PANW palette. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Decided "at the moment", so recorded as provisional with the cost of changing course written down: moving to products or tabs at the top level rewrites every route, which means a redirect for every published page and re-binding for anything the OpenAPI group config generates. The revisit trigger is therefore route stability, not page count — reconsider before the first substantial batch of pages publishes and acquires inbound links, not after. Nothing else in the project depends on the choice; page contracts, provenance, the loop and the spec handoff are all route-shaped rather than primitive-shaped. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Prisma AIRS AI Gateway docs — project kickstart
Kickstarts the initiative described in the v2 Mintlify handoff (included under
prisma-airs/_project/). This is scaffolding, planning, and tooling — no productdocumentation is authored here, and no existing published page is modified.
Scope decision
The whole corpus is Prisma AIRS AI Gateway, rebranded in place. The other tabs are modules of
it, not separate products.
The migration surface
A third
navigation.versions[]entry,"Prisma AIRS", inserted between"Latest"and"Virtual Keys (Deprecated)"."Latest"stays first and therefore stays the default version,so nobody lands on the new surface by accident.
Pages join it one at a time, only after passing the grounding gate. Its page count is the
INIT 1 progress metric.
prisma-airs/overview.mdxseeds it and deliberately carries no product capability claims —navigation and branding only, which is the only kind of page writable before KB access exists.
Its grounding status is recorded in an MDX comment on the page itself, along with the standing
rule that the
prisma-airs-ctasnippet is not used in this version.Planning artifacts —
prisma-airs/_project/00-capability-register.md01-reader-journeys.md02-page-contracts.mdwriting-style-guide.md.03-provenance-model.md04-operator-questions.md05-naming-rules.md06-changelog-contribution-path.mdNaming rule
Approved. The operative line: if a reader would type it or a machine would
parse it, it does not change. So
portkey_ai,PORTKEY_*,x-portkey-*,api.portkey.ai,and
PORTKEY_GATEWAY_URLall stay; prose renames.Explicitly warns against a global find-and-replace — it would break every code sample.
update-changelogskill (+82 lines)Two additions that need no KB access:
prisma-airs/_project/releases/<repo>@<tag>.yamlbefore any prose is written. One assertionper fact, not per PR; state the fact, not the edit. The
supersedesfield is the one thatmatters — a release that quietly changes a documented default is the expensive case, because
nothing in the release notes flags that a guide is now wrong.
published; guides are not. A release entry is a dated observation that stays true forever,
so rewriting it to match a current guide destroys the record of what a customer on that
version actually got.
No backfill of existing entries: reconstructing assertions from published prose would violate
handoff §3 rule 7, which forbids treating documentation as evidence for its own claims.
.mintignore— a correctionThe first commit claimed the planning artifacts were safe because they are
.md, not.mdx,and absent from navigation. Both halves were wrong, and
mint validatecaught it.Mintlify processes
.mdas well as.mdx, and navigation omission does not exclude a filefrom the build or from the public exports (
llms.txt/llms-full.txt). This is the traphandoff §2 warns about — "A page absent from navigation is not necessarily private."
The real mechanism is a repo-root
.mintignore(gitignore syntax), now added forprisma-airs/_project/. The claim is corrected everywhere it was made.Validation
mint validate— one pre-existing warning, unrelated to this PR and deliberately notfixed here (see below)
mint broken-links— no broken links in the new page. 66 pre-existing across 48 files,23 of them under
virtual_key_old/; untouched by decision.mint dev— confirmed workingDeliberately not fixed
Standing instruction: do not modify non-Prisma-AIRS docs. Two pre-existing issues were
found while working here and are being left alone:
docs.jsonreferencesproduct/mcp-gateway/authentication, which is a directory whoselanding page is
index.mdx. Mintlify does not resolve a directory to its index, so that naventry points at nothing and
mint validatefails repo-wide on it. The one-line fix is onbranch
fix/mcp-gateway-auth-nav, ready to land separately whenever wanted.(
writing-style-guide.md,MCP-Gateway-Roadmap.md,create-split-prs.sh, two stray PNGs).Decisions already taken — 2026-09-07
Recorded in
04-operator-questions.md; no open reviewer questions remain except the KB.CTAs,
status.portkey.ai, and the compliance and uptime claims on the entry page.withdrawal.
schedule; guide and reference patches wait for KB acceptance.
prisma-airs-ctasnippet — not used in the Prisma AIRS version. It announces thePortkey → Prisma AIRS transition, which is redundant on pages that are already Prisma AIRS.
mint a11y/mint test— deferred, to be adopted later.Blocked
Page authoring is blocked on Prisma AIRS KB MCP access. The only MCP server configured here,
mcp-gateway, times out and appears by name to be the MCP Gateway product rather than the KB.Steps 4b (MCP submission) and the dependency-index upgrade are specced and waiting.
🤖 Generated with Claude Code