The scope encompasses:

• Term identification: Parsing web page text to identify KERI/SSI terminology
• Definition retrieval: Accessing the unified glossary JSON data structure
• UI presentation: Displaying interactive buttons and definition popups
• Multi-source aggregation: Presenting definitions from multiple authoritative glossaries

Relationship to Protocol Specifications

kerific is not a protocol implementation but rather a documentation accessibility tool. It does not implement KERI protocol operations, CESR encoding, or ACDC credential processing. Instead, it serves as a companion tool that helps users understand the terminology used in protocol specifications, implementation documentation, and technical discussions.

The tool's relationship to specifications is indirect but valuable: by making terminology more accessible, it lowers barriers to understanding formal specifications and implementation guides for the KERI Suite.

Key Features & Capabilities

Dual Distribution Model

kerific's most distinctive architectural feature is its dual distribution strategy, which addresses different user needs and technical constraints:

Bookmarklet Implementation

The bookmarklet variant provides:

• Zero-installation access: Users drag a JavaScript link to their bookmarks bar
• On-demand activation: Click the bookmark to inject kerific into the current page
• Rapid updates: Changes to the hosted JavaScript are immediately available to all users
• Cross-browser compatibility: Works in any browser supporting JavaScript bookmarklets

The bookmarklet operates by injecting two elements into the host page:

1. A <script> tag loading index.js from weboftrust.github.io/kerific/
2. A <link> tag loading index.css for styling

The implementation includes duplicate prevention logic that checks for existing kerific instances (identified by the unique ID kerific-83450285767488) and removes them before injection, ensuring clean re-activation.

Limitation: The bookmarklet approach is blocked on websites with strict Content Security Policy (CSP) headers that prohibit inline script execution or external script loading.

Chrome Extension Implementation

The Chrome Web Store extension addresses the CSP limitation:

• CSP bypass: Extension permissions allow script injection even on CSP-protected sites
• Persistent availability: No need to click a bookmark for each page
• Browser integration: Appears in the browser's extension toolbar
• Chromium compatibility: Works in Chrome, Brave, Edge, and other Chromium-based browsers

Trade-off: Extension updates require Chrome Web Store approval, introducing approximately 24-hour delays for new versions. This makes the extension less agile than the bookmarklet for rapid iteration.

Term Matching and Identification

The core functionality revolves around intelligent term matching against the unified SSI dictionary. The implementation:

1. Parses web page text: Scans paragraph content for potential terminology matches
2. Matches against dictionary: Compares identified words/phrases against the JSON glossary database
3. Handles aliases: Recognizes multiple variations of the same canonical term
4. Respects context: Avoids false positives through contextual analysis

The matching algorithm must balance precision (avoiding false positives) with recall (catching all relevant terms). The implementation leverages the extensive alias system in the KERI/GLEIF glossary, which includes 459 canonical terms with numerous variations.

Interactive UI Components

When kerific identifies matching terms, it injects interactive button elements below the containing paragraph. These buttons:

• Display term names: Show which glossary terms were identified
• Trigger definition popups: Click to view full definitions
• Support multiple sources: Present definitions from various glossaries
• Maintain page layout: Minimize disruption to the original page design

The UI implementation uses CSS to ensure visual consistency while adapting to different website styles and layouts.

Integration with KERISSE Unified Dictionary

kerific's definition data comes from the KERISSE unified glossary, which aggregates terminology from multiple authoritative sources:

• KERI/GLEIF canonical glossary: 459 core terms with extensive aliases
• ToIP (Trust over IP) glossaries: Community-maintained definitions
• Implementation-specific glossaries: Terms from KERIpy, KERIA, and other projects
• External SSI glossaries: Broader self-sovereign identity terminology

The unified dictionary is compiled into a large JSON file that kerific loads and queries. This architecture provides:

• Offline capability: Once loaded, definitions are available without additional network requests
• Consistency: All users see the same authoritative definitions
• Maintainability: Updates to the glossary automatically propagate to kerific users

Multi-Glossary Definition Display

A key feature is the ability to present multiple definitions for the same term from different sources. This is valuable because:

• Different glossaries may emphasize different aspects of a concept
• Some definitions are more technical while others are more accessible
• Comparing definitions helps users develop deeper understanding
• Source attribution maintains intellectual property respect

The UI allows users to navigate between different glossary sources for each identified term.

Installation & Setup

Bookmarklet Installation

1. Navigate to the kerific page on the WebOfTrust documentation site
2. Locate the bookmarklet link (typically displayed as a draggable button)
3. Drag the link to your bookmarks bar (ensure the bookmarks bar is visible)
4. Verify installation by checking that the bookmark appears in your bar

Usage: Click the kerific bookmark while viewing any web page to activate term matching and definition display.

Chrome Extension Installation

1. Visit the Chrome Web Store at the kerific extension page:
   • URL: chromewebstore.google.com/detail/kerific/ckbmkbbmnfbeecfmoiohobcdmopekgmp
2. Click "Add to Chrome" (or equivalent for Brave/Edge)
3. Confirm permissions when prompted
4. Verify installation by checking for the kerific icon in your browser toolbar

Usage: The extension activates automatically on supported pages, or can be toggled via the toolbar icon.

Browser Compatibility

Supported Browsers:

• Google Chrome (primary target)
• Brave Browser (Chromium-based)
• Microsoft Edge (Chromium-based)
• Other Chromium-based browsers

Unsupported:

• Firefox (extension not available in Firefox Add-ons)
• Safari (no Safari extension version)

Dependencies

kerific has minimal external dependencies:

• GitHub Pages hosting: Requires weboftrust.github.io to be accessible
• JSON glossary file: Must be able to load the unified dictionary
• Modern JavaScript support: Requires ES6+ browser capabilities

No server-side components are required; kerific operates entirely client-side.

Usage & API

User Interaction Model

kerific is designed for passive, non-intrusive operation:

1. Automatic term detection: No user action required for term identification
2. On-demand definition access: Click buttons to view definitions
3. Minimal page modification: Preserves original content and layout
4. Dismissible UI: Definitions can be closed without page reload

Programmatic Interface

While kerific is primarily a user-facing tool, the implementation exposes certain programmatic interfaces:

Injection API (Bookmarklet)

The bookmarklet uses a simple injection pattern:

// Check for existing instance
if (document.getElementById('kerific-83450285767488')) {
  // Remove existing instance
  document.getElementById('kerific-83450285767488').remove();
}

// Inject script
var script = document.createElement('script');
script.id = 'kerific-83450285767488';
script.src = 'https://weboftrust.github.io/kerific/index.js';
document.body.appendChild(script);

// Inject stylesheet
var link = document.createElement('link');
link.rel = 'stylesheet';
link.href = 'https://weboftrust.github.io/kerific/index.css';
document.head.appendChild(link);

This pattern ensures:

• Unique identification: The specific ID prevents conflicts
• Clean re-injection: Existing instances are removed before adding new ones
• Proper resource loading: Script and styles load from GitHub Pages

Extension API (Chrome)

The Chrome extension variant uses the Chrome Extension API for content script injection:

// Manifest V3 content script declaration
{
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["index.js"],
    "css": ["index.css"]
  }]
}

This declarative approach provides:

• Automatic injection: No user action required
• Broad compatibility: Works on all URLs (subject to Chrome restrictions)
• Isolated execution: Runs in a sandboxed content script context

Configuration Options

The current implementation does not expose user-configurable options in the documented sources. Potential future configuration might include:

• Term matching sensitivity
• Definition display preferences
• Glossary source selection
• UI styling customization

However, these features are not present in the current implementation as documented.

Related Implementations

KERISSE (KERI Suite Search Engine)

KERISSE is the complementary search platform that provides:

• Full-text search: Typesense-powered search across KERI documentation
• Glossary compilation: Aggregates multiple glossary sources into the unified dictionary
• Documentation hosting: Docusaurus-based documentation site

kerific depends on KERISSE for its glossary data, making KERISSE a critical upstream dependency.

WOT-terms Repository

The WOT-terms repository serves as:

• Terminology management: Central repository for KERI/GLEIF canonical terms
• Glossary source: Primary source for the 459 canonical terms
• Documentation hub: Hosts the Docusaurus site that includes kerific documentation

kerific is part of the WOT-terms ecosystem but maintained in a separate repository.

Kerific Discord Bot

A related implementation provides similar functionality in the Discord platform:

• Repository: github.com/kordwarshuis/kerific-discord-bot
• Hosting: Deployed on Heroku
• Function: Retrieves KERI information on demand in Discord servers

This demonstrates the extensibility of the kerific concept beyond browser-based implementations.

Integration Points

kerific integrates with:

1. GitHub Pages: Hosts the core JavaScript and CSS files
2. Chrome Web Store: Distributes the extension variant
3. KERISSE API: Consumes the unified glossary JSON
4. WebOfTrust documentation: Embedded in the broader documentation ecosystem

Implementation Architecture

Data Flow

1. Glossary compilation: KERISSE scrapes and aggregates multiple glossary sources
2. JSON generation: Unified dictionary compiled into large JSON file
3. GitHub Pages deployment: JSON and kerific code deployed to weboftrust.github.io
4. Client-side loading: Browser loads kerific script and glossary data
5. Term matching: JavaScript parses page content and matches against dictionary
6. UI injection: Interactive buttons and definition displays added to page

Performance Considerations

The implementation must balance functionality with performance:

• JSON size: Large glossary file requires efficient loading and caching
• DOM manipulation: Term matching and UI injection must not block page rendering
• Memory usage: Dictionary must be held in memory for fast lookups
• Network requests: Minimize additional requests after initial load

Security Model

kerific operates with minimal permissions:

• Bookmarklet: Runs with page-level JavaScript permissions
• Extension: Requires content script injection permission
• No data collection: Does not transmit user data or browsing history
• Read-only operation: Does not modify page content beyond UI injection

The implementation follows privacy-by-design principles, operating entirely client-side without server-side tracking or analytics.

Governance and Intellectual Property

kerific's implementation respects the intellectual property of glossary sources:

• Apache-2 licensed content: Freely used from GitHub repositories
• Explicit permissions: Obtained for specific blogs and websites (e.g., keri.one)
• Attribution: Contributors acknowledged on the KERISSE site
• Dispute resolution: GitHub issues tracker for IP concerns

This governance model balances open educational resource principles with respect for content creators' rights.

Future Development Directions

While not explicitly documented, potential enhancements could include:

• Firefox extension: Expand browser support beyond Chromium
• Mobile support: Adapt for mobile browser environments
• Offline mode: Enhanced caching for fully offline operation
• Custom glossaries: Allow users to add personal or organization-specific terms
• API exposure: Programmatic access for other tools and integrations

These directions would extend kerific's utility while maintaining its core mission of making KERI/SSI terminology more accessible to technical practitioners.

Implementers should consider:

• Lazy loading: Load glossary data only when first term is matched
• Compression: Serve gzipped JSON to reduce transfer size
• Incremental parsing: Use streaming JSON parsers for large datasets

Term Matching Algorithm

The implementation must handle:

• Alias resolution: Map multiple term variations to canonical forms
• Case sensitivity: Handle different capitalizations of the same term
• Partial matches: Decide whether to match substrings or whole words only
• False positives: Avoid matching common words that happen to be glossary terms

The documented sources do not specify the exact matching algorithm, suggesting this is an implementation detail that may vary.

UI Injection Strategy

kerific injects UI elements into host pages, requiring careful consideration of:

• CSS isolation: Prevent host page styles from breaking kerific UI
• Layout preservation: Minimize disruption to original page layout
• Accessibility: Ensure injected elements are keyboard-navigable and screen-reader friendly
• Performance: Avoid excessive DOM manipulation that could slow page rendering

Content Security Policy Handling

The CSP limitation of the bookmarklet is a fundamental constraint:

• Many modern websites use strict CSP headers that block inline scripts
• The extension variant bypasses this through browser extension permissions
• No pure JavaScript solution exists for CSP-protected sites without extension privileges

Implementers should:

• Detect CSP failures: Provide user feedback when bookmarklet is blocked
• Recommend extension: Guide users to the extension variant for CSP-protected sites
• Document limitations: Clearly communicate which approach works in which contexts

Update Propagation

The update model differs between variants:

• Bookmarklet: Updates to index.js and index.css on GitHub Pages immediately affect all users on next activation
• Extension: Updates require Chrome Web Store submission, review, and user acceptance of updates

This creates a version skew problem where bookmarklet users may have newer features than extension users for 24+ hours after release.

Privacy and Security Considerations

kerific's client-side-only architecture provides strong privacy guarantees:

• No server-side tracking: No user data transmitted to servers
• No analytics: No usage metrics collected
• Read-only operation: Does not modify page content beyond UI injection
• Minimal permissions: Extension requires only content script injection

Implementers should maintain these privacy properties and resist feature additions that would require server-side components or data collection.

Integration with KERISSE

The dependency on KERISSE for glossary data creates an architectural coupling:

• kerific cannot function without access to the unified dictionary
• Changes to KERISSE's glossary compilation affect kerific's term coverage
• KERISSE downtime directly impacts kerific functionality

This suggests a service-oriented architecture where kerific is a consumer of KERISSE's glossary service.

Browser Compatibility Matrix

Supported:

• Chrome (primary target)
• Brave (Chromium-based)
• Edge (Chromium-based)
• Other Chromium browsers

Unsupported:

• Firefox (no extension available)
• Safari (no extension available)

The Chromium-only support is a significant limitation for cross-browser adoption. Future implementations might consider:

• Firefox extension: Port to Firefox Add-ons using WebExtensions API
• Safari extension: Develop Safari App Extension variant
• Bookmarklet universality: Ensure bookmarklet works across all browsers

Governance and IP Compliance

The implementation must respect intellectual property of glossary sources:

• Only scrape content with explicit permission or compatible licenses (Apache-2)
• Provide attribution for all sources
• Maintain a dispute resolution process via GitHub issues
• Remove sources upon legitimate IP claims

This governance model is documented in the IP rights scraping policy and should be followed by all contributors.