c25. Perspective Augmentation Plan

Goal

Augment the existing c25 inventory-index work with a second layer of planning: one map perspective for each major entity family in the AI ecosystem.

This plan is intentionally additive to the existing PLAN.md.

The shared multi-perspective inventory model is already created. The open question for c25 is not whether these perspectives should exist, but how qmap should express them spatially and operationally.

Execution companion:

• PERSPECTIVE-IMPLEMENTATION-PLAN.md

The current inventory story remains the anchor:

• agents stay central to the first inventory view
• repositories and files remain the most proven middle layer
• MCP servers, tools, and sub-agents remain the initial capability surfaces

This augmentation asks the next question:

• what should qmap show when we pivot the same ecosystem around Sessions, Agents, Users, MCP Servers, Models, API Keys, Endpoints, Tools & Skills, Repos / Files, and Secondary Calls?

Existing Foundation

Treat these as already established inputs, not proposed net-new concepts:

• the shared multi-perspective inventory model
• the ten inventory entity families
• the broader inventory and detail-page framing explored in design
• the current in-flight c25 inventory graph, wrapper seam, and synthetic scenario work

This plan is therefore about:

• extending the current qmap implementation to honor those existing perspectives
• deciding what each perspective should emphasize spatially
• identifying where grouping alone is enough and where summaries, compression, or special treatment are required

Augmentation Principle

Do not replace the current c25 work with ten unrelated views.

Instead:

• keep one canonical ecosystem graph
• preserve QMapInventoryIndex as the shared inventory/index wrapper
• add one wrapper component per item type for perspective-specific maps
• add a second c25 experiment page dedicated to item-specific maps
• let each item-specific wrapper decide what deserves spatial treatment, what deserves grouping, and what should stay as compact summary metadata

What To Show Beyond Connections And Groupings

For every perspective, the useful dimensions are broader than "what is it connected to?" and "how should it be grouped?"

Also consider:

• intensity: what is hot versus incidental
• recency: what changed in the selected timeframe
• directionality: who initiated the interaction and where work fanned out
• ownership: who owns the focal entities
• access mode: read, write, invoke, delegate, retry, fail over
• concentration: many-to-one and one-to-many hotspots
• blast radius: what else depends on this entity
• provenance: why this entity is present in the view
• health: failures, retries, latency, stale age
• cost: tokens, spend, expensive concentration points
• compression: which dense areas should collapse into summaries

Wrapper-Per-Item Contract

Each item-specific map should have its own wrapper component, fed by data that is specific to that view rather than by a generic all-entities payload alone.

Each wrapper should define:

• focusEntityType
• inputDataShape
• primaryConnections
• defaultGroupBy
• alternateGroupModes
• defaultStats
• defaultFilters
• defaultSelectionExpansion
• summaryModules

Recommended first-pass rule:

• use view-specific synthetic data contracts for item maps
• keep semantics on tags and data shape before inventing new meshes
• only add new meshes after the wrapper proves real value

This is specifically a qmap wrapper strategy layered on top of the existing shared inventory model, not a replacement for that model.

Perspective Matrix

Sessions

Useful question:

• what happened in this run, and what did it touch?

Show:

• session -> agent
• session -> user
• session -> models
• session -> MCP servers
• session -> tools and skills
• session -> repos and files
• session -> endpoints
• session -> secondary calls

Useful groupings:

• phase
• status
• team
• environment
• session type
• repo or workspace

Useful extras:

• phase segmentation or replay
• token and cost totals
• read/write/invoke/delegate breakdown
• errors and retries
• touched-entity counts

Agents

Useful question:

• what does this agent do across sessions, repos, tools, and downstream systems?

Show:

• agent -> sessions
• agent -> users
• agent -> models
• agent -> MCP servers
• agent -> tools and skills
• agent -> repos and files
• agent -> endpoints
• agent -> secondary calls

Useful groupings:

• owner team
• business unit
• agent role
• model family
• environment
• primary repo

Useful extras:

• concurrency
• delegation tree
• tool mix
• hot repos and files
• cost and reliability summaries

Users

Useful question:

• how is this user using the AI ecosystem, through which agents, and with what access footprint?

Show:

• user -> sessions
• user -> agents
• user -> repos and files
• user -> tools and skills
• user -> models
• user -> API keys they own or trigger
• user -> endpoints indirectly reached through sessions

Useful groupings:

• team
• role
• business unit
• workspace
• permission tier
• usage frequency

Useful extras:

• top agents used
• collaboration overlap
• sensitive assets touched
• usage spikes
• write footprint

MCP Servers

Useful question:

• which agents and sessions rely on this MCP server, and what work fans out from it?

Show:

• MCP server -> agents
• MCP server -> sessions
• MCP server -> repos and files
• MCP server -> tools and skills
• MCP server -> endpoints
• MCP server -> secondary calls

Useful groupings:

• capability class
• owner team
• provider
• trust tier
• environment
• auth method

Useful extras:

• latency and error rate
• fan-in across teams
• permission scope
• hot operations
• blast radius

Models

Useful question:

• where is this model used, through which agents and endpoints, and at what cost/reliability profile?

Show:

• model -> agents
• model -> sessions
• model -> endpoints
• model -> API keys
• model -> tools and skills
• model -> secondary calls

Useful groupings:

• provider
• model family
• reasoning class
• cost tier
• latency tier
• endpoint

Useful extras:

• token volume
• cost concentration
• fallback chains
• failover and retry patterns
• provider split

API Keys

Useful question:

• where is this credential used, who owns it, and how much blast radius does it carry?

Show:

• API key -> endpoints
• API key -> models
• API key -> MCP servers
• API key -> sessions
• API key -> agents
• API key -> users or service owners

Useful groupings:

• owner
• provider
• environment
• scope
• permission tier
• rotation window

Useful extras:

• age since rotation
• dormant versus hot keys
• anomaly markers
• shared credential risk
• cost attribution

Important note:

• API keys may need lower-visual-weight treatment plus stronger summary sidecars earlier than other perspectives

Endpoints

Useful question:

• which external or internal endpoints are being hit, by whom, and with what performance profile?

Show:

• endpoint -> sessions
• endpoint -> agents
• endpoint -> MCP servers
• endpoint -> models
• endpoint -> API keys
• endpoint -> secondary calls

Useful groupings:

• provider
• region
• environment
• protocol
• auth type
• reliability tier

Useful extras:

• latency heat
• error clusters
• ingress versus egress split
• failover chains
• network-boundary crossings

Tools & Skills

Useful question:

• what capabilities are actually being used, by which agents, and what do those capabilities touch downstream?

Show:

• tool or skill -> agents
• tool or skill -> sessions
• tool or skill -> MCP servers
• tool or skill -> repos and files
• tool or skill -> models
• tool or skill -> secondary calls

Useful groupings:

• capability family
• built-in versus custom
• owner team
• permission class
• invocation frequency
• access mode

Useful extras:

• common tool pairings
• downstream touch breadth
• side-effect intensity
• essential versus dormant capabilities
• delegation initiation markers

Repos / Files

Useful question:

• where is work happening in code and content, and which actors are concentrating on the same assets?

Show:

• repo -> agents
• repo -> sessions
• repo -> users
• repo -> tools and skills
• repo -> MCP servers
• repo -> files
• file -> secondary calls when delegated work lands there

Useful groupings:

• repo
• path or directory
• language
• owner team
• business unit
• access mode
• branch or worktree

Useful extras:

• hotspot files
• co-touch clusters
• read versus write density
• ownership gaps
• critical-path assets

Important note:

• this remains the strongest existing c25 anchor and should likely continue to lead the first implementation wave

Secondary Calls

Useful question:

• what indirect or delegated work was created by primary activity, and how much amplification did it introduce?

Show:

• secondary call -> parent session
• secondary call -> parent agent
• secondary call -> initiating tool or skill
• secondary call -> models
• secondary call -> MCP servers
• secondary call -> repos and files
• secondary call -> endpoints

Useful groupings:

• call type
• depth
• cause
• provider
• status
• retry versus purposeful delegation

Useful extras:

• tree depth
• amplification ratio
• retry loops
• fan-out summaries
• hidden cost
• provenance chain back to the initiating user or agent

Important note:

• this perspective is likely to need collapse and summary behavior early to avoid turning into unreadable fan-out

Shared Grouping Vocabulary

Across perspectives, validate a common set of grouping modes:

• Entity Type
• Focus Entity
• Team
• Business Unit
• Owner
• Environment
• Provider
• Capability Class
• Repository
• Time Bucket
• Status
• Flat

Each perspective should expose only the subset that genuinely helps that entity family.

Shared Non-Spatial Summary Modules

Some signals should likely render as summary panels or strips rather than as more nodes:

• top connected entities
• token and cost totals
• failure counts
• latency bands
• recency distribution
• write concentration
• rotation age
• retry percentage
• delegation-depth histogram

This will matter most for:

• Models
• API Keys
• Secondary Calls
• dense Repos / Files scenarios

Synthetic Data Expansion First Checklist

Recommended execution strategy:

• expand the existing c25 synthetic data before implementing all perspective presets
• keep one canonical scenario pack rather than inventing perspective-specific fixture sets too early
• use the richer synthetic graph to pressure-test grouping, summaries, and scene density before adding new visuals

1. Extend The Entity Catalog

Add first-class synthetic entities for the perspectives that are not yet fully covered:

• Session
• User
• Model
• API Key
• Endpoint
• Secondary Call

Keep the current entities as they are:

• AI Agent
• Repository
• File
• MCP Server
• Tool
• Sub-Agent

Implementation goal:

• every perspective in this augmentation plan should have at least one real backing entity family in the synthetic scenario graph

2. Extend The Flow Catalog

Add explicit synthetic relationships for the missing perspective stories:

• user -> session
• session -> agent
• session -> model
• session -> mcp-server
• session -> tool
• session -> sub-agent
• session -> repository
• session -> endpoint
• agent -> model
• model -> endpoint
• api-key -> model
• api-key -> endpoint
• api-key -> mcp-server
• secondary-call -> model
• secondary-call -> endpoint
• secondary-call -> repository
• secondary-call -> file
• secondary-call -> parent session
• secondary-call -> parent agent

Implementation goal:

• every perspective can expand outward through real graph edges rather than inferred metadata alone

3. Expand Actor Tags

Add enough tags for grouping, filtering, and summaries to feel real:

• owner
• ownerType
• team
• businessUnit
• environment
• provider
• status
• securityTier
• capabilityClass
• modelFamily
• endpointRegion
• endpointKind
• accessMode
• sessionId
• sessionType
• repo
• callDepth
• parentCallId

Implementation goal:

• perspective groupings should be powered by scenario metadata that already exists on the actors

4. Expand Flow Tags

Add enough flow metadata to support perspective-specific scene logic:

• protocol
• operation
• direction
• latencyBucket
• errorState
• retryCount
• costWeight
• tokenWeight
• timeBucket
• initiatedBy
• credentialId
• parentSessionId
• parentCallId

Implementation goal:

• flows should support hotspot styling, filtering, and summary computation without custom one-off logic per perspective

5. Expand Scenario Stats

Add perspective-facing stats to the synthetic scenario output:

• sessions
• users
• models
• apiKeys
• endpoints
• secondaryCalls
• errorCount
• retryCount
• estimatedCost
• tokenVolume

Implementation goal:

• the experiment header and future perspective panels can read directly from scenario stats instead of recomputing everything ad hoc

6. Preserve Deterministic Tiers

Keep the current tiering structure:

• demo
• teamspace
• enterprise
• global-enterprise

But ensure each tier now includes enough variety to exercise all entity families.

Minimum coverage recommendation:

• demo should include at least one user, one session, one model, one endpoint, one API key, and one secondary call
• teamspace should include believable cross-team ownership and provider variation
• enterprise should include enough repeated usage to expose hotspots and dependency concentration
• global-enterprise should include enough fan-out to pressure-test compression and summary modules

7. Keep The Current c25 Story Legible

Do not let the synthetic expansion break the existing inventory anchor.

Protect these current c25 strengths:

• agent-centered readability
• repository -> file legibility
• MCP/tool/sub-agent distinction through tags
• deterministic density tuning

Implementation goal:

• the richer data model should broaden c25, not blur its original inventory story

8. Define Perspective-Readiness Gates

Before implementing each perspective preset, confirm the synthetic data can answer its core question.

Perspective-readiness checklist:

• the focal entity exists as a first-class synthetic actor or explicit summary target
• the primary outbound and inbound relationships exist in the synthetic graph
• there are enough tags to support at least two meaningful grouping modes
• there are enough stats or flow tags to support the default summary strip
• the scenario includes at least one believable hotspot or concentration pattern for that perspective

9. Execute In Two Passes

Pass one:

• expand the synthetic scenario generator and scenario outputs
• verify the experiment still renders cleanly across all four scenario tiers
• verify the existing inventory view remains readable

Pass two:

• add perspective presets on top of the richer scenario graph
• start with the perspectives that can immediately exploit the new entities

10. First Execution Slice

Concrete next slice for c25:

• extend inventoryScenarios.js with Session, User, Model, API Key, Endpoint, and Secondary Call
• add the missing flow families and tags
• expand stats and meta
• update the experiment header to expose the new counts
• sanity-check all four tiers for scene density regressions

Completion criteria for this slice:

• current c25 inventory rendering still works
• the synthetic data now covers all ten perspective families
• the next step can shift from data modeling to perspective-specific scene behavior

Experiment Structure

Mirror the proven c23 pattern with two c25 experiment entry points:

• page 1: the existing inventory/index experiment
• page 2: an item-specific map lab that loads one wrapper component at a time

The second page should:

• use a select dropdown to switch which item-specific wrapper component is mounted
• feed that mounted component with synthetic data shaped specifically for that view
• keep shared scene controls where possible so wrappers can be compared under similar conditions

Delivery Order

Add the augmentation in waves:

Wave 1

• Agents
• Sessions
• Repos / Files
• MCP Servers
• Tools & Skills

Reason:

• these are closest to the current in-flight c25 graph and can prove the wrapper-per-item strategy fastest

Wave 2

• Models
• Endpoints
• Users

Reason:

• these deepen the inventory into provider, access, and operational dependency views

Wave 3

• API Keys
• Secondary Calls

Reason:

• these are the most likely to force compression, provenance, and special summary treatment

Augmentation Success Criteria

This companion plan is successful when:

• the existing c25 inventory work remains intact
• the already-created shared multi-perspective inventory is respected rather than redefined
• the second c25 experiment page can switch between item-specific wrappers from a dropdown
• each wrapper answers a distinct useful question, not just a recolored version of the same map
• dense perspectives have an explicit compression or summary strategy
• the repo/file-centered inventory story remains legible while the broader ecosystem atlas grows around it