Skip to content

PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 PER-14113 PER-14116 per-14119 PER-14118 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration #612

Merged
EliMoshkovich merged 8 commits intodan/per-13548-agentsecurity-write-docs-for-agentsecurityfrom
per-13548-docs-phase-2
Mar 11, 2026

Conversation

@dshoen619
Copy link
Contributor

  • Add 7 Mermaid diagrams to architecture.mdx: system architecture
    overview, data flow, admin setup flow, user consent flow (with
    upstream OAuth branch), authorization decision flow (7-step
    middleware chain), trust ceiling (min logic) visualization, and
    policy architecture
  • Add platform.mdx with Platform UI documentation (dashboard, hosts,
    MCP servers, humans management)
  • Add permit-integration.mdx covering Permit schema, ReBAC model,
    and derived roles
  • Update guide.mdx with step-by-step screenshots for host creation,
    MCP server import, user access grants, and consent flow
  • Update overview.mdx and index.mdx with refined terminology and
    navigation
  • Add Mermaid diagram styling improvements (edge labels, background
    colors) in docusaurus.config.js and custom.scss
  • Add 12 platform UI screenshots

@dshoen619 dshoen619 self-assigned this Mar 10, 2026
@dshoen619 dshoen619 changed the title PER-14120 PER -14117 PER-14114 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration PER-14120 PER-14117 PER-14114 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration Mar 10, 2026
@dshoen619 dshoen619 changed the title PER-14120 PER-14117 PER-14114 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration Mar 10, 2026
  permit integration, consent service, auth methods, on-prem
  deployment

  - PER-14120: Add 7 Mermaid diagrams to architecture.mdx (system
  overview, data flow, admin setup, consent flow with upstream OAuth,
  authorization decision flow, trust ceiling)
  - PER-14112: Expand permit-integration.mdx with derived role
  breakdown, allow-list enforcement, tenant model, default policy,
  customization guide
  - PER-14118: Add dedicated audit-logs.mdx page (screenshots pending)
  - Add consent-service.mdx, authentication-methods.mdx,
  on-prem-deployment.mdx
  - Add consent flow screenshots
  - Update guide.mdx and sidebars.js
@dshoen619 dshoen619 changed the title PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 PER-14113 PER-14116 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration Mar 10, 2026
@dshoen619 dshoen619 changed the title PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 PER-14113 PER-14116 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 PER-14113 PER-14116 per-14119 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration Mar 10, 2026
@dshoen619 dshoen619 changed the title PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 PER-14113 PER-14116 per-14119 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 PER-14113 PER-14116 per-14119 PER-14118 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration Mar 11, 2026
EliMoshkovich and others added 4 commits March 11, 2026 10:07
Critical fixes:
- C4: Fix Permit API endpoint /v2/api/tokens/scope → /v2/api-key/scope
  in architecture.mdx sequence diagram
- C5: Fix Redis key pattern host:{subdomain} → host_lookup:{subdomain}
  in two architecture.mdx sequence diagrams
- C1/C2/C3: Rewrite session expiry in consent-service.mdx — 90-day TTL
  is a rolling inactivity timeout (not absolute), remove non-existent
  30-day soft expiry, clarify these are MCP session TTLs not consent TTLs

Important fixes:
- I1: Add "(coming soon)" to HITL mentions in overview.mdx (meta + body)
- I2: Add missing NGINX routes (/api/consent/*, /api/mcp/*) to data flow table
- I3: Add "common pitfall" warning about granting user access in guide.mdx
- M1: Add explanation of mcp-remote tool in client config section
- M3: Clarify OPA/OPAL are used under the hood by Permit.io PDP

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- architecture.mdx: permission denied error code is -32004, not -32001
  (-32001 is UNAUTHORIZED for missing/invalid tokens)
- consent-service.mdx: clarify that the profile-to-server relation is
  set by the admin and verified as a trust ceiling, not "confirmed"

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Rewrite index.mdx: lead with outcomes instead of jargon (ReBAC, OPA,
  OPAL), organize navigation into "Start Here" and "Go Deeper" tiers
- Add "New to MCP?" callout in overview.mdx for non-AI-expert readers
- Reorder sidebar: Getting Started moved up to position 2, Architecture
  and Permit Integration moved to bottom as deep-dive reference
- Relabel Architecture → "Architecture Deep Dive" and Permit.io
  Integration → "Permit.io Integration Deep Dive"
- Remove on-prem-deployment.mdx (not ready for publication)
- Remove on-prem references and deployment table from architecture.mdx
- Update sidebars.js to match new page order

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Resolve conflicts in architecture.mdx, guide.mdx, and index.mdx when
merging from dan/per-13548-agentsecurity-write-docs-for-agentsecurity.

- index.mdx: keep customer-friendly opening, incorporate prerequisites
  from base branch
- architecture.mdx: keep detailed technical diagrams (appropriate for
  deep-dive page), keep upstream OAuth step, keep deployment one-liner
- guide.mdx: take base branch's improved audit log wording

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@EliMoshkovich EliMoshkovich merged commit e62b448 into dan/per-13548-agentsecurity-write-docs-for-agentsecurity Mar 11, 2026
@EliMoshkovich EliMoshkovich deleted the per-13548-docs-phase-2 branch March 11, 2026 15:53
EliMoshkovich added a commit that referenced this pull request Mar 12, 2026
…provements (#610)

* Refactor MCP Permissions documentation to Agent Security terminology

Updated titles, descriptions, and content across multiple files to reflect the rebranding from MCPermit to Agent Security. Enhanced clarity on the architecture, setup, and core concepts of the Agent Security framework, ensuring consistency in terminology and improving user guidance for implementation.

* Update Agent Security docs for new admin-controlled user flow

Reflect the new platform flow where admins explicitly grant users access to MCP servers, users pick from a list during consent, and audit logs live in app.agent.security. Add authentication methods reference section covering email, social, passkey, SAML, and OIDC.

* Update package-lock.json and remove yarn.lock; modify architecture documentation for MCP permissions to clarify hosted gateway URL and enhance resource mapping details.

* Update architecture and guide documentation for Agent Security to clarify hosted gateway URL and refine trust level classification details.

* Clarify user access management for MCP servers in Agent Security documentation. Update instructions on granting access, pre-authorization, and trust levels to enhance user understanding of the consent flow and permissions.

* Fix mermaid node label clipping issue in custom.scss by adjusting overflow and adding padding for multi-line text.

* Refine Agent Security documentation for MCP permissions, enhancing clarity on API key usage, host definitions, and user consent flow. Update terminology for user permissions and trust levels to improve understanding of the setup process.

* Enhance Agent Security documentation for MCP permissions by refining descriptions of the proxy/gateway role, trust level classifications, and deployment options. Update terminology for clarity and include upcoming features for human-in-the-loop approvals.

* Update Agent Security documentation to indicate that the single control point for authorization, audit, and anomaly detection is planned. This change enhances clarity regarding future capabilities in the MCP permissions architecture.

* Fix mermaid edge labels overlapping with arrow lines in custom.scss by adjusting the fill and opacity properties for better visibility.

* Update Agent Security documentation to include direct links to relevant sections in the Dashboard, MCP Servers, and Humans pages. This enhances navigation and clarity for users managing hosts, servers, and user permissions.

* Enhance Agent Security documentation by updating trust level classifications, refining deployment options, and adding a new `user_profile` resource for relationship-based permission derivation. Clarify examples and terminology for better understanding of agent roles and permissions.

* Enhance mermaid diagram styling in docusaurus.config.js and custom.scss by adding theme variables for edge labels and improving background color handling for better visibility in flowcharts and sequence diagrams.

* Address PR #610 review feedback from Eli Moshkovich on Agent Security docs

Fixes accuracy, content, and style issues flagged during code review,
verified against the agent-security staging branch source of truth.

- Fix Low trust level description to reflect it is a default fallback,
  not an explicit pattern match (architecture.mdx, guide.mdx)
- Expand user_profile explanation with min() derivation logic and
  3-way chain: Agent → UserProfile → MCP Server (architecture.mdx)
- Complete Medium and High trust pattern lists to match tool-trust.ts
- Clarify that heuristics match keywords anywhere in tool name (guide.mdx)
- Replace stale Agent Configuration Examples table with trust-level-based
  examples using actual MCP clients and server keys (architecture.mdx)
- Update consent UI screenshot to current design and move image path
  from /img/mcpermit/ to /img/agent-security/ (overview.mdx)
- Update info callout to describe current consent flow (overview.mdx)
- Add trailing newline to custom.scss

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add platform UI screenshots to Agent Security Getting Started guide

Add 12 screenshots walkthrough of the Agent Security platform UI to the
Getting Started guide, covering every step of the admin and user flows:

- Create Host page and environment creation option
- Dashboard with Gateway MCP URL and client config snippets
- MCP Servers list page
- Import MCP Server flow (connect URL + review/configure tools)
- Human user detail page with MCP server access and connected agents
- Agent Users list page
- User consent flow: sign-in, server selection, trust level setting
- Host settings with authentication methods

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update consent server selection screenshot with cropped version

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Address PR #610 review feedback: fix trust level notation, PDP placement, identity docs, and blur staging domains

- Fix trust level pattern notation in architecture.mdx to use keyword-based matching instead of misleading prefix `_*` notation (item 1)
- Remove consent-trust-level.png screenshot from guide.mdx step 4 (item 2)
- Move PDP out of Gateway subgraph into its own Authorization subgraph in mermaid diagram (item 4)
- Clarify when each identity format (human|subject vs agent|client_id) is used (item 7)
- Remove speculative latency numbers from planned deployment table (item 8)
- Replace screenshots with versions that blur staging.agent.security domains (item 6)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix OAuth timing in overview.mdx consent flow documentation

Correct the info callout to accurately describe what "Authorize Agent" does
(issues auth code, not OAuth redirect), add upstream OAuth as a separate step
before trust level selection, and merge admin step to include user access grants.

Resolves PER-14103

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add agent-browser skill with comprehensive documentation and templates

- Introduced `skills-lock.json` to manage agent-browser skill dependencies.
- Added detailed documentation for the `agent-browser` skill, covering browser automation, authentication patterns, proxy support, session management, and video recording.
- Included templates for authenticated sessions, content capture, and form automation to streamline user workflows.
- Implemented a snapshot and reference system to optimize interaction with web elements.

This commit enhances the agent-browser capabilities, providing users with robust tools for web automation and testing.

* Fix PR #610 items 3 and 5: match guide text to screenshots

- Update Create Host section to describe Subdomain/Environment/Project
  fields instead of the incorrect "Permit API Key" field
- Remove outdated prerequisite about project/environment-scoped API key
- Replace agents.png with screenshot from a populated host
- Add agent-detail.png showing MCP server permissions and trust levels
- Update Agents section text to describe both list and detail views

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix JWT issuer attribution, ReBAC diagram accuracy, and consent flow
   language consistency

  - architecture.mdx: Correct JWT issuer from gateway to consent
  service
  - architecture.mdx: Add UserProfile intermediary to ReBAC diagram
  with note linking to full model
  - guide.mdx: Add authorize_agent_screen.png screenshot to trust
  level step
  - overview.mdx + guide.mdx: Align consent button label to "Accept"
  matching actual UI

* Add missing troubleshooting cases and clarify audit log locations in guide.mdx

Adds 5 missing failure modes to the troubleshooting table (OAuth credentials/PKCE
errors, re-consent trust level ceiling, session expiry, upstream_mcp with no access,
audit log location confusion), clarifies that audit logs exist in both the Agent
Security platform and Permit.io dashboard, and adds session expiry behavior to the
consent flow section. Cross-links added throughout for navigation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add Platform UI to architecture diagrams and sequences

- Replace "Core Components" with full system architecture diagram showing
  all components: Platform UI, Consent Service, Gateway, Permit.io Cloud,
  PDP, PostgreSQL, Redis, and upstream MCP servers
- Update admin setup sequence to route through Platform UI instead of
  directly to Gateway: Admin → Platform → Gateway/Permit
- Add Platform UI and Permit.io as participants in first-time connection
  sequence diagram
- Remove Embedded WASM / Remote PDP deployment table (Permit PDP internals,
  not Agent Security deployment options)

Resolves: PER-14105

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix domain restrictions semantics to document intersection behavior

The guide incorrectly implied OR semantics for domain restrictions.
Actual behavior is intersection: a domain must be allowed by BOTH the
global list AND the method-specific list. Added warning example showing
that per-method domains do not bypass the global list.

Resolves: PER-14104

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix API reference link and add prerequisites to index.mdx

- Clarify API reference link as "Permit.io API Reference" instead of
  implying it is an Agent Security-specific API
- Add one-sentence description of what Agent Security does
- Add prerequisites section (Permit.io account + Platform access)
- Add link to Platform UI at app.agent.security

Resolves: PER-14106

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix broken link, user_profile key format, and JWT issuance
  description in architecture.mdx

  - Replace broken permit-integration link with internal anchor to
  trust ceiling section
  - Correct user_profile instance key from :subject to :user_id (| not
   allowed in Permit keys)
  - Clarify JWT issuance as two-step code exchange to match sequence
  diagram

* PER-14120 PER-14117 PER-14114 PER-14110 PER-14111 PER-14112 PER-14113 PER-14116 per-14119 PER-14118 Agent Security Docs Phase 2: Architecture diagrams, platform    guides, and Permit integration   (#612)

* PER 14120,14114,14117

* PER-14110,14111,14112

* Add Phase 2 docs: architecture diagrams, audit logs,
  permit integration, consent service, auth methods, on-prem
  deployment

  - PER-14120: Add 7 Mermaid diagrams to architecture.mdx (system
  overview, data flow, admin setup, consent flow with upstream OAuth,
  authorization decision flow, trust ceiling)
  - PER-14112: Expand permit-integration.mdx with derived role
  breakdown, allow-list enforcement, tenant model, default policy,
  customization guide
  - PER-14118: Add dedicated audit-logs.mdx page (screenshots pending)
  - Add consent-service.mdx, authentication-methods.mdx,
  on-prem-deployment.mdx
  - Add consent flow screenshots
  - Update guide.mdx and sidebars.js

* added audit log screenshots for PER-14118

* fix: correct technical inaccuracies in Agent Security docs

Critical fixes:
- C4: Fix Permit API endpoint /v2/api/tokens/scope → /v2/api-key/scope
  in architecture.mdx sequence diagram
- C5: Fix Redis key pattern host:{subdomain} → host_lookup:{subdomain}
  in two architecture.mdx sequence diagrams
- C1/C2/C3: Rewrite session expiry in consent-service.mdx — 90-day TTL
  is a rolling inactivity timeout (not absolute), remove non-existent
  30-day soft expiry, clarify these are MCP session TTLs not consent TTLs

Important fixes:
- I1: Add "(coming soon)" to HITL mentions in overview.mdx (meta + body)
- I2: Add missing NGINX routes (/api/consent/*, /api/mcp/*) to data flow table
- I3: Add "common pitfall" warning about granting user access in guide.mdx
- M1: Add explanation of mcp-remote tool in client config section
- M3: Clarify OPA/OPAL are used under the hood by Permit.io PDP

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: correct MCP error code and clarify consent service wording

- architecture.mdx: permission denied error code is -32004, not -32001
  (-32001 is UNAUTHORIZED for missing/invalid tokens)
- consent-service.mdx: clarify that the profile-to-server relation is
  set by the admin and verified as a trust ceiling, not "confirmed"

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: improve customer-friendliness and remove on-prem page

- Rewrite index.mdx: lead with outcomes instead of jargon (ReBAC, OPA,
  OPAL), organize navigation into "Start Here" and "Go Deeper" tiers
- Add "New to MCP?" callout in overview.mdx for non-AI-expert readers
- Reorder sidebar: Getting Started moved up to position 2, Architecture
  and Permit Integration moved to bottom as deep-dive reference
- Relabel Architecture → "Architecture Deep Dive" and Permit.io
  Integration → "Permit.io Integration Deep Dive"
- Remove on-prem-deployment.mdx (not ready for publication)
- Remove on-prem references and deployment table from architecture.mdx
- Update sidebars.js to match new page order

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: eli <eli@permit.io>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

* [PER-14108] Update consent flow documentation and add new screenshots (#611)

* Update consent flow documentation and add new screenshots

- Revise consent flow steps in the guide and overview documents to reflect updated user experience.
- Introduce new images for sign-in, server selection, trust level setting, OAuth redirect, and processing consent.
- Add an empty state screenshot for users without server access.

This enhances clarity and visual guidance for users navigating the MCP client connection process.

* Add Advanced Features page for Agent Security

Introduces a new documentation page showcasing six advanced capabilities
(fingerprinting, snitch skills, shadow agent detection, HITL, workflow
intents, and time-limited consent) with Mermaid diagrams and status badges.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add troubleshooting guidance for duplicate MCP server connections

Introduces a warning about the potential issues caused by having the same MCP server configured through both Agent Security and as a direct connection. Clarifies that this can lead to the AI agent bypassing the gateway, and provides a specific fix to remove or disable the duplicate connection.

* Remove orphaned consent flow images

Delete 3 unreferenced images replaced by new consent-flow screenshots.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: correct TTL descriptions and soften roadmap language in advanced-features

- C1/C2/C3: Rewrite Time-Limited Consent section to accurately describe
  90-day rolling inactivity TTL (not absolute), clarify soft TTL is not
  yet implemented, and distinguish MCP session TTLs from consent permissions
- M4: Soften "coming soon" feature descriptions to avoid setting concrete
  expectations for unimplemented features

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: eli <eli@permit.io>

* remove advanced-features.mdx and on-prem references from architecture

- Delete orphaned advanced-features.mdx (not in sidebar, not linked)
- Change "Cloud or On-Prem" to "Cloud" in architecture diagram
- Change "on-prem AI" to "co-located AI" in integration patterns table

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: remove last on-prem reference in architecture data flow table

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: correct host creation UI, session TTLs, tools display, and add token refresh docs

- Align host creation steps in platform.mdx, host-setup.mdx, and
  architecture.mdx to match actual UI (Project + Environment dropdowns
  instead of Permit API Key field)
- Document both session TTLs accurately: soft 30-day inactivity TTL and
  hard 90-day absolute TTL (was incorrectly showing only 90-day inactivity)
- Fix tools display description in consent-service.mdx to match actual UI
  (flat list with dynamic Allowed/Denied badges, not grouped by trust level)
- Add upstream token auto-refresh note to the getting started guide
- Fix mislabeled session type in consent-service.mdx info box

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add advanced features documentation and update sidebar

- Introduced a new documentation page for Advanced Features, detailing capabilities such as agent fingerprinting, shadow agent detection, and human-in-the-loop approvals.
- Updated the sidebar to include a link to the new Advanced Features page, enhancing navigation for users seeking information on upcoming functionalities.

* blurred out url for mcp connection to agent security gateway

* fix: address Or's review — Enterprise banner, remove coming soon, zoomable diagrams, rename section

- Add Enterprise-only callout banner to Advanced Features page
- Remove all "coming soon" content from overview, architecture, and advanced features
- Remove Roadmap table and Planned Policy Enhancements section from architecture
- Create ZoomableDiagram component for click-to-expand Mermaid diagrams
- Move MCP Permissions from AI Security to top-level "Permit MCP Gateway" section
- Update all internal cross-references and add redirects for old URLs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: improve ZoomableDiagram — actual zoom + fix hint overlap

- Render mermaid SVG at 1800px width in overlay for real zoom effect
- Make overlay use full 95vw/90vh with scroll for pan navigation
- Change hint from absolute-positioned to flow layout to avoid overlapping heading
- Prevent body scroll when overlay is open

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: fix clipped edge label in system architecture diagram

- Add overflow:visible fix for mermaid edgeLabel foreignObject elements
- Split long edge label "/mcp, /oauth/*, /.well-known/*" with line break
  to prevent mermaid from miscalculating the label container size

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: remove coming-soon feature content from Advanced Features page

- Hide all unreleased feature sections (Agent Fingerprints, Snitch Skills,
  Shadow Agent Detection, HITL, Workflow Intent) inside MDX comments
  so they're preserved for future use but invisible to readers
- Keep only Time-Limited Consent which is partially available today
- Clean up Time-Limited Consent description (remove "future releases" language)
- Update index.mdx link description to match

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: add TODO comment to hidden advanced features sections

Remind future editors to review and update the content against
the actual implementation before uncommenting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: restore advanced features content (now implemented)

Uncomment all previously hidden feature sections — Agent Fingerprints,
Snitch Skills, Shadow Agent Detection, HITL, and Workflow Intent
Descriptions are now implemented. Enterprise-only banner remains.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address docs review — OAuth routing, dynamic MCPs, list_tools behavior, sidebar ordering

- Fix OAuth discovery sequence diagram to route /.well-known/oauth-authorization-server to Gateway (not Consent Service)
- Document Dynamic MCPs feature (architecture, consent-service, permit-integration)
- Fix absolute server allow-list statement to account for dynamic MCPs opt-in
- Document /mcp/{static_mcp_key} path-based server selection
- Document list_tools visibility behavior (all tools visible, enforcement at call_tool)
- Fix Time-Limited Consent framing to distinguish built-in session expiry from Enterprise configurable windows
- Fix Policy-as-code claim (remove misleading Rego/GitOps/unit tests reference)
- Fix sidebar position conflicts (host-setup: 4→4.2, advanced-features: 4→9)
- Use realistic subdomain in architecture Redis key diagram

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: simplify advanced features page — light enterprise teaser with clear labels

Rewrite to be a scannable overview with an `Enterprise` badge on each feature.
Remove detailed mermaid diagrams, lengthy explanations, and use cases.
Keep each section to 2-3 sentences describing what the feature does.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: align advanced features with mock-ui — naming, add Permission Receipts

- Rename "Agent Fingerprints via Interrogation" → "Agent Fingerprinting"
- Rename "Workflow Intent Descriptions" → "Intent-Based Access Control"
- Add "Permission Receipts" Enterprise feature
- Keep "Inject Security Snitch Skills" and "HITL" (future features)
- Keep "Enterprise" tier labeling (source of truth over mock-ui "Pro")
- Update index page reference

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: make advanced features page customer-friendly

- Rename "Inject Security Snitch Skills" → "In-Session Monitoring" (clearer)
- Remove raw `Enterprise` code-block badges (redundant with top banner)
- Soften banner from :::caution to :::note (upsell, not warning)
- Simplify descriptions — focus on customer value, remove jargon
- Polish CTA section at bottom

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: polish advanced features as upsell page

- Add value-prop intro sentence before features
- Simplify Enterprise banner with single CTA (schedule demo)
- Condense session expiry info callout
- Strengthen bottom CTA with clear primary action

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: surface Dynamic MCPs in Getting Started guide and Platform page

Dynamic MCPs was only documented in the Architecture Deep Dive — too
buried for customers to find. Now documented in:
- Getting Started guide (after "Edit an MCP server", step 3)
- Platform page (Settings section, before Authentication methods)
Both link to the Architecture page for deeper technical details.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: single source of truth for Dynamic MCPs in Getting Started

- Platform page: trim to one-liner + link to guide
- Architecture page: trim to Permit-specific detail + link to guide
- Getting Started guide remains the authoritative section

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: move Dynamic MCPs source of truth to Platform Settings

The toggle lives in host Settings, so Platform is the natural home.
All other pages now link to Platform#dynamic-mcps instead of
duplicating content or linking to Architecture.

- platform.mdx: full instructions, toggle behavior, warning
- guide.mdx: tip callout + link to Platform
- architecture.mdx: Permit-specific detail + link to Platform
- consent-service.mdx: updated link to Platform
- permit-integration.mdx: updated link to Platform

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Carlos Mion <carlos@permit.io>
Co-authored-by: David Shoen <dbshoen@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: dshoen619 <107557675+dshoen619@users.noreply.github.com>
Co-authored-by: eli <eli@permit.io>
Co-authored-by: Carlos Mion <mion.carlos23@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants