Knowledge Map
Navigable, cited maps of your repos and workspaces — architecture diagrams, documentation, and links to sources
Status: Partial. Today, Knowledge Map covers public GitHub repositories through the deepwiki_search tool — architecture context, documentation, and citations grounded in source. Auto-generated, navigable maps for your connected private repos and workspaces — a sidebar browser, diagrams, and steering via .opulent/wiki.json — are Planned. Knowledge Map is its own primitive: it is not Knowledge notes and not Memory.
Overview
Knowledge Map turns a repository into a navigable, cited map: architecture diagrams, summaries of the codebase, and links back to source. Use it to get up to speed on unfamiliar parts of a codebase quickly.
Today this works for public GitHub repositories via the deepwiki_search tool. Auto-generated maps for your connected private repos and workspaces — the kind you'd browse from the sidebar — are Planned; the configuration described below is how you'll steer that generation once it ships.
Ask Opulent will use Knowledge Map to understand and find the relevant context in your codebase, combining advanced code search with Knowledge Map to produce detailed, context-grounded answers. (Ask Opulent is a product target.)
When workspace maps ship, Knowledge Map will be autogenerated as you connect repositories during onboarding.
For public repositories
Knowledge Map for public GitHub repositories is available today through deepwiki_search. It surfaces architecture context, documentation, and links to source code so you can understand unfamiliar codebases quickly, and it answers complex questions about a codebase with specific, context-grounded responses.
The full workspace Knowledge Map experience — advanced code search, planning, and Session creation over your private repos — is Planned in the Opulent app. Public coverage via deepwiki_search and the Knowledge Map MCP provide documentation and Q&A capabilities today.
Point deepwiki_search at a public GitHub repository — React, TensorFlow, LangChain, and many others — to explore its structure, or submit your own public repo for indexing.
Access public-repo documentation and search programmatically
Steering Knowledge Map (Planned)
The .opulent/wiki.json file lets you steer Opulent's default map-generation behavior, which is especially important for large repositories that may hit built-in limits.
When workspace Knowledge Map ships, if a .opulent/wiki.json file is found in your repository's root directory during map generation, we'll use the provided repo_notes and pages to steer generation. If pages is provided, we'll bypass the default cluster-based planning and create exactly the pages you specify. This ensures that the important parts of your codebase are documented even when the automatic system would otherwise skip them.
Configuration Format
Create a .opulent/wiki.json file in your repository root with the following structure:
{
"repo_notes": [
{
"content": "This repository contains the main UI components in the cui/ folder, which should be prioritized in documentation",
"author": "Team Lead"
}
],
"pages": [
{
"title": "CUI Components Overview",
"purpose": "Document the cui/ folder structure and main UI components",
"parent": null
},
{
"title": "Authentication System",
"purpose": "Document the authentication flow and related components",
"parent": null
},
{
"title": "Login Components",
"purpose": "Detailed documentation of login-related UI components",
"parent": "Authentication System"
}
]
}
Configuration Options
repo_notes (Array)
Provides context and guidance to help the map system understand your repository better.
- content (string, required): The note content (max 10,000 characters)
- author (string, optional): Who wrote the note
pages (Array, optional)
Specifies exactly which pages should be created in your map.
This field is optional. If you only include repo_notes, the system will still generate a map, using your notes to guide the structure and focus without requiring you to outline every page.
When you do provide pages, they are treated as explicit instructions. Only the pages you define in the JSON will be generated, no more, no less.
- title (string, required): The page title (must be unique and non-empty)
- purpose (string, required): What this page should document
- parent (string, optional): Title of the parent page for hierarchical organization
- page_notes (array, optional): Additional notes specific to this page
Validation Limits
- Maximum 30 pages (80 for enterprise)
- Maximum 100 total notes (repo_notes + all page_notes combined)
- Maximum 10,000 characters per note
- Page titles must be unique and non-empty
Practical Examples
Example 1: Repo Notes to Guide Map Generation
If you prefer not to define specific pages, you can provide only repo_notes to help guide map generation. This lets Opulent create the map structure automatically while still taking your priorities and areas of focus into account. This is useful when you want better coverage and emphasis without having to explicitly outline every page yourself.
{
"repo_notes": [
{
"content": "The repository contains three main areas: the frontend/ folder with React components, the backend/ folder with API services, and the infra/ folder with deployment scripts. Documentation should emphasize how these parts interact and highlight the backend API layer as the highest priority."
}
]
}
Example 2: Ensuring Specific Folders Are Documented
If your large repository has important folders that aren't being included in the map, explicitly specify them:
{
"repo_notes": [
{
"content": "The cui/ folder contains critical UI components that must be documented. The backend/ folder contains the main API logic. The utils/ folder has shared utilities used throughout the codebase."
}
]
}
Example 3: Addressing Missing Components
If you notice certain parts of your codebase aren't being documented:
{
"repo_notes": [
{
"content": "The testing/ directory contains important test utilities and patterns that developers need to understand. The scripts/ directory has deployment and maintenance scripts that are crucial for operations."
}
]
}
Example 4: Hierarchical Documentation Structure
For complex repositories, organize pages hierarchically:
{
"repo_notes": [
{
"content": "This is a full-stack application with distinct frontend, backend, and shared components that should be documented separately but with clear relationships."
}
],
"pages": [
{
"title": "Architecture Overview",
"purpose": "High-level overview of the application architecture and how components interact"
},
{
"title": "Frontend",
"purpose": "Frontend application structure and components",
"parent": "Architecture Overview"
},
{
"title": "React Components",
"purpose": "Detailed documentation of React components, their props, and usage",
"parent": "Frontend"
},
{
"title": "State Management",
"purpose": "How application state is managed, including stores and data flow",
"parent": "Frontend"
},
{
"title": "Backend",
"purpose": "Backend services, APIs, and data layer",
"parent": "Architecture Overview"
},
{
"title": "API Endpoints",
"purpose": "REST API documentation including endpoints, request/response formats",
"parent": "Backend"
}
]
}
Best Practices
1. Use Repo Notes Strategically
- Provide context about which parts of your codebase are most important
- Mention specific folders or components that should be prioritized
- Explain relationships between different parts of your system
2. Organize Pages Logically
- Start with high-level overview pages
- Use parent-child relationships to create clear hierarchies
- Group related functionality together
3. Be Specific in Page Purposes
- Clearly state what each page should document
- Mention specific directories, files, or concepts to focus on
- Provide enough detail for the system to understand your intent
4. Address Known Gaps
- If you know certain parts of your codebase are being missed, explicitly include them
- Use descriptive titles that make it clear what should be covered
Troubleshooting Common Issues
"Only certain folders are being documented"
This is the classic large repository problem.
Solution: Use .opulent/wiki.json to explicitly specify which parts of your codebase should be documented.
Start with updating only repo_notes, and regenerate the map with that additional context to see if the updated map will include the missing folders. Only add the pages array if necessary.
"Important components are missing from the map"
Add specific pages for these components and use repo_notes to emphasize their importance.
Remember: Knowledge Map will generate only the pages included in this array, so ensure all pages are present, not just the missing page.
{
"repo_notes": [
{
"content": "The [missing-component] directory is critical to the application and must be documented thoroughly."
}
],
"pages": [
{
"title": "Critical Component Name",
"purpose": "Document the [missing-component] directory and its functionality"
}
]
}
Getting Started
- Create
.opulent/wiki.jsonin your repository root - Add repo_notes explaining your codebase structure and priorities
- If necessary, specify all pages you want created with clear titles and purposes
- Commit the file and regenerate your map
Once workspace Knowledge Map ships, the system will create documentation based on your explicit instructions rather than fully automatic analysis, ensuring comprehensive and more accurate coverage of large repositories.