@vorionsys/shared-constants 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @vorionsys/shared-constants
 
-Single source of truth for the Vorion ecosystem - trust tiers, domains, capabilities, rate limits, error codes, and more.
+Single source of truth for the Vorion ecosystem -- canonical trust tiers, domain configuration, capability definitions, rate limits, error codes, API versions, product catalog, and UI themes.
 
 ## Installation
 
@@ -8,6 +8,19 @@ Single source of truth for the Vorion ecosystem - trust tiers, domains, capabili
 npm install @vorionsys/shared-constants
 ```
 
+## What This Package Provides
+
+| Module | Description |
+|--------|-------------|
+| **Tiers** | The BASIS 8-tier trust model (T0-T7) with score ranges, names, colors, and helper functions |
+| **Domains** | All Vorion, Agent Anchor, and Cognigate domains, API endpoints, emails, GitHub links, and npm package names |
+| **Capabilities** | Tier-gated capability definitions with categories and constraint metadata |
+| **Products** | Product catalog for both Vorion (open source) and Agent Anchor (commercial) with status and version info |
+| **Rate Limits** | Per-tier rate-limiting configurations and monthly quota definitions |
+| **Error Codes** | Standardized error codes (E1xxx-E7xxx) with HTTP status, categories, retry info, and message templates |
+| **API Versions** | Version management for Cognigate, Trust, Logic, BASIS, and CAR Spec APIs |
+| **Themes** | UI theme tokens (4 themes) with CSS custom-property generation |
+
 ## Quick Start
 
 ```typescript
@@ -17,50 +30,48 @@ import {
   scoreToTier,
   API_ENDPOINTS,
   CAPABILITIES,
+  getCapabilitiesForTier,
 } from '@vorionsys/shared-constants';
 
-// Convert score to tier
+// Convert a trust score to its tier
 const tier = scoreToTier(750); // TrustTier.T4_STANDARD
 
-// Get tier info
+// Look up tier metadata
 const info = TIER_THRESHOLDS[TrustTier.T4_STANDARD];
-console.log(info.name);        // "Standard"
+console.log(info.name);         // "Standard"
 console.log(info.min, info.max); // 650, 799
+console.log(info.color);        // "#22c55e"
 
-// Check capabilities
+// List capabilities available at a tier
 const caps = getCapabilitiesForTier(TrustTier.T4_STANDARD);
-```
-
-## Features
+console.log(caps.map(c => c.code));
+// ["CAP-READ-PUBLIC", "CAP-GENERATE-TEXT", ..., "CAP-ESCALATE-HUMAN"]
 
-- **Trust Tiers (T0-T7)**: Complete 8-tier trust model with thresholds, names, colors, and helper functions
-- **Domains & URLs**: All Vorion, AgentAnchor, and Cognigate domains and API endpoints
-- **Capabilities**: Tier-gated capability definitions with category filtering
-- **Products**: Product catalog with status and category metadata
-- **Rate Limits**: Per-tier rate limiting and quota configurations
-- **Error Codes**: Standardized error codes with categories and retry information
-- **API Versions**: Version management for Cognigate, Trust, Logic, BASIS, and CAR APIs
-- **Themes**: UI theme tokens with CSS variable generation
+// Get an API endpoint
+const apiUrl = API_ENDPOINTS.cognigate.production;
+// "https://cognigate.dev/v1"
+```
 
 ## Trust Tiers
 
-The BASIS 8-tier trust model (score range 0-1000):
+The BASIS 8-tier trust model (score range 0--1000):
 
 | Tier | Score | Name | Description |
 |------|-------|------|-------------|
-| T0 | 0-199 | Sandbox | Isolated, no external access |
-| T1 | 200-349 | Observed | Read-only, monitored |
-| T2 | 350-499 | Provisional | Basic operations, heavy supervision |
-| T3 | 500-649 | Monitored | Standard operations with monitoring |
-| T4 | 650-799 | Standard | External API access, policy-governed |
-| T5 | 800-875 | Trusted | Cross-agent communication |
-| T6 | 876-950 | Certified | Admin tasks, minimal oversight |
-| T7 | 951-1000 | Autonomous | Full autonomy, self-governance |
+| T0 | 0--199 | Sandbox | Isolated, no external access, observation only |
+| T1 | 200--349 | Observed | Read-only, sandboxed execution, monitored |
+| T2 | 350--499 | Provisional | Basic operations, heavy supervision |
+| T3 | 500--649 | Monitored | Standard operations with continuous monitoring |
+| T4 | 650--799 | Standard | External API access, policy-governed |
+| T5 | 800--875 | Trusted | Cross-agent communication, delegated tasks |
+| T6 | 876--950 | Certified | Admin tasks, agent spawning, minimal oversight |
+| T7 | 951--1000 | Autonomous | Full autonomy, self-governance, strategic only |
 
 ## Subpath Imports
 
+Import only the module you need to minimize bundle size:
+
 ```typescript
-// Import only what you need
 import { TrustTier, scoreToTier } from '@vorionsys/shared-constants/tiers';
 import { VORION_DOMAINS, API_ENDPOINTS } from '@vorionsys/shared-constants/domains';
 import { CAPABILITIES, getCapabilitiesForTier } from '@vorionsys/shared-constants/capabilities';
@@ -68,45 +79,387 @@ import { VORION_PRODUCTS } from '@vorionsys/shared-constants/products';
 import { RATE_LIMITS, getRateLimits } from '@vorionsys/shared-constants/rate-limits';
 import { ERROR_CODES, getErrorByCode } from '@vorionsys/shared-constants/error-codes';
 import { API_VERSIONS, getCurrentVersion } from '@vorionsys/shared-constants/api-versions';
+import { THEMES, getActiveTheme, themeToCssVars } from '@vorionsys/shared-constants/themes';
 ```
 
-## API Reference
+## Usage Examples
 
-### Tiers
+### Trust Tier Helpers
 
 ```typescript
-scoreToTier(750)                          // TrustTier.T4_STANDARD
-getTierName(TrustTier.T5_TRUSTED)         // "Trusted"
-getTierColor(TrustTier.T3_MONITORED)      // "#eab308"
-getTierMinScore(TrustTier.T4_STANDARD)    // 650
-meetsTierRequirement(750, TrustTier.T3_MONITORED) // true
-parseTier('T3')                           // TrustTier.T3_MONITORED
-parseTier('TRUSTED')                      // TrustTier.T5_TRUSTED
+import {
+  TrustTier,
+  scoreToTier,
+  getTierName,
+  getTierColor,
+  getTierMinScore,
+  getTierMaxScore,
+  getTierCode,
+  meetsTierRequirement,
+  parseTier,
+  ALL_TIERS,
+} from '@vorionsys/shared-constants';
+
+scoreToTier(750);                                 // TrustTier.T4_STANDARD
+getTierName(TrustTier.T5_TRUSTED);                // "Trusted"
+getTierColor(TrustTier.T3_MONITORED);             // "#eab308"
+getTierMinScore(TrustTier.T4_STANDARD);           // 650
+getTierMaxScore(TrustTier.T4_STANDARD);           // 799
+getTierCode(TrustTier.T4_STANDARD);               // "T4"
+meetsTierRequirement(750, TrustTier.T3_MONITORED); // true
+parseTier('T3');                                   // TrustTier.T3_MONITORED
+parseTier('TRUSTED');                              // TrustTier.T5_TRUSTED
+ALL_TIERS;                                         // [T0, T1, T2, T3, T4, T5, T6, T7]
 ```
 
-### Rate Limits
+### Domains and Endpoints
 
 ```typescript
+import {
+  VORION_DOMAINS,
+  AGENTANCHOR_DOMAINS,
+  COGNIGATE_DOMAINS,
+  API_ENDPOINTS,
+  VORION_EMAILS,
+  GITHUB,
+  NPM_PACKAGES,
+  ALL_DOMAINS,
+  DOMAIN_ALIASES,
+} from '@vorionsys/shared-constants';
+
+VORION_DOMAINS.basis;                  // "https://basis.vorion.org"
+AGENTANCHOR_DOMAINS.trust;             // "https://trust.vorion.org"
+COGNIGATE_DOMAINS.main;                // "https://cognigate.dev"
+API_ENDPOINTS.cognigate.production;    // "https://cognigate.dev/v1"
+API_ENDPOINTS.agentAnchor.sandbox;     // "https://sandbox.vorion.org/v1"
+VORION_EMAILS.security;               // "security@vorion.org"
+GITHUB.vorion.mainRepo;               // "https://github.com/vorionsys/vorion"
+NPM_PACKAGES.vorion.sharedConstants;   // "@vorionsys/shared-constants"
+```
+
+### Capabilities
+
+```typescript
+import {
+  CapabilityCategory,
+  CAPABILITIES,
+  getCapabilitiesForTier,
+  getCapability,
+  isCapabilityAvailable,
+  getCapabilityMinTier,
+  getCapabilitiesByCategory,
+  getAllCapabilityCodes,
+} from '@vorionsys/shared-constants';
+
+// Get all capabilities unlocked at T4 or below
+const caps = getCapabilitiesForTier(TrustTier.T4_STANDARD);
+
+// Look up a single capability
+const cap = getCapability('CAP-AGENT-DELEGATE');
+// { code: "CAP-AGENT-DELEGATE", name: "Task Delegation", unlockTier: T5_TRUSTED, ... }
+
+// Check if available
+isCapabilityAvailable('CAP-FILE-WRITE', TrustTier.T3_MONITORED); // true (unlocks at T2)
+
+// Get minimum tier needed
+getCapabilityMinTier('CAP-AGENT-SPAWN'); // TrustTier.T6_CERTIFIED
+
+// Filter by category
+const apiCaps = getCapabilitiesByCategory(CapabilityCategory.API_ACCESS);
+```
+
+### Products
+
+```typescript
+import {
+  ProductCategory,
+  ProductStatus,
+  VORION_PRODUCTS,
+  AGENTANCHOR_PRODUCTS,
+  ALL_PRODUCTS,
+  getProduct,
+  getProductsByCategory,
+  getProductsByStatus,
+  getProductsByOrganization,
+} from '@vorionsys/shared-constants';
+
+const basis = getProduct('basis');
+// { id: "basis", name: "BASIS", status: "ga", url: "https://basis.vorion.org", ... }
+
+const gaProducts = getProductsByStatus(ProductStatus.GA);
+const openSource = getProductsByCategory(ProductCategory.OPEN_SOURCE);
+const vorionProducts = getProductsByOrganization('vorion');
+```
+
+### Rate Limits and Quotas
+
+```typescript
+import {
+  TrustTier,
+  RATE_LIMITS,
+  TIER_QUOTAS,
+  getRateLimits,
+  wouldExceedLimit,
+  formatRateLimit,
+  getQuota,
+  isUnlimited,
+} from '@vorionsys/shared-constants';
+
 const limits = getRateLimits(TrustTier.T4_STANDARD);
-// { requestsPerMinute: ..., requestsPerHour: ..., ... }
+// { requestsPerSecond: 20, requestsPerMinute: 600, burstLimit: 50, ... }
+
+wouldExceedLimit(TrustTier.T4_STANDARD, 'minute', 599); // false
+wouldExceedLimit(TrustTier.T4_STANDARD, 'minute', 600); // true
 
-wouldExceedLimit(currentCount, TrustTier.T4_STANDARD, 'requestsPerMinute');
-formatRateLimit(limits); // Human-readable string
+formatRateLimit(TrustTier.T4_STANDARD);
+// "20/s, 600/min, 10000/hr"
+
+const quota = getQuota(TrustTier.T7_AUTONOMOUS);
+isUnlimited(quota.monthlyApiCalls); // true (-1 means unlimited)
 ```
 
 ### Error Codes
 
 ```typescript
-const error = getErrorByCode('AUTH_001');
-// { code, message, category, httpStatus, retryable }
+import {
+  ErrorCategory,
+  ERROR_CODES,
+  getErrorByCode,
+  getErrorsByCategory,
+  getRetryableErrors,
+  formatErrorMessage,
+  createErrorResponse,
+} from '@vorionsys/shared-constants';
 
+// Look up error by its code string
+const err = getErrorByCode('E1001');
+// { code: "E1001", httpStatus: 401, category: "auth", message: "API key is missing...", retryable: false }
+
+// Use a named error constant
+const response = createErrorResponse(
+  ERROR_CODES.TRUST_TIER_INSUFFICIENT,
+  { currentTier: 'T2', requiredTier: 'T4' },
+  'req_abc123',
+);
+// { error: { code: "E5001", message: "Trust tier T2 insufficient. Required: T4.", ... }, status: 403 }
+
+// Get all retryable errors (useful for retry logic)
 const retryable = getRetryableErrors();
-const response = createErrorResponse('AUTH_001', { detail: 'Token expired' });
+
+// Get errors by category
+const authErrors = getErrorsByCategory(ErrorCategory.AUTH);
+```
+
+### API Versions
+
+```typescript
+import {
+  VersionStatus,
+  API_VERSIONS,
+  getCurrentVersion,
+  getVersionDefinition,
+  isVersionSupported,
+  isVersionDeprecated,
+  getStableVersions,
+  buildApiUrl,
+  VERSION_HEADERS,
+  COGNIGATE_CURRENT_VERSION,
+  BASIS_SPEC_VERSION,
+} from '@vorionsys/shared-constants';
+
+getCurrentVersion('cognigate');   // "v1"
+getCurrentVersion('basis');       // "v1"
+BASIS_SPEC_VERSION;               // "1.0.0"
+
+isVersionSupported('cognigate', 'v1');  // true
+isVersionDeprecated('cognigate', 'v1'); // false
+
+buildApiUrl('https://cognigate.dev', 'v1', 'agents/lookup');
+// "https://cognigate.dev/v1/agents/lookup"
+
+const stableVersions = getStableVersions('trust');
+
+VERSION_HEADERS.REQUEST_VERSION;  // "X-API-Version"
+```
+
+### Themes
+
+```typescript
+import {
+  ACTIVE_THEME,
+  THEMES,
+  getActiveTheme,
+  getAllThemeIds,
+  themeToCssVars,
+} from '@vorionsys/shared-constants';
+
+ACTIVE_THEME;              // "midnight_cyan"
+getAllThemeIds();           // ["midnight_cyan", "indigo_authority", "obsidian_amber", "arctic_glass"]
+
+const theme = getActiveTheme();
+console.log(theme.accent);      // "#06b6d4"
+console.log(theme.bgPrimary);   // "#0a0a0f"
+console.log(theme.fontFamily);  // "'Inter', -apple-system, ..."
+
+// Generate CSS custom properties for injection
+const cssVars = themeToCssVars('midnight_cyan');
+// "--bg-primary: #0a0a0f; --accent: #06b6d4; ..."
 ```
 
+## API Reference
+
+### Tiers (`@vorionsys/shared-constants/tiers`)
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `TrustTier` | enum | Trust tier enum (T0_SANDBOX through T7_AUTONOMOUS) |
+| `TIER_THRESHOLDS` | const | Score ranges, names, descriptions, and colors for each tier |
+| `scoreToTier(score)` | function | Convert a 0-1000 score to its `TrustTier` |
+| `getTierThreshold(tier)` | function | Get the full `TierThreshold` object for a tier |
+| `getTierName(tier)` | function | Get human-readable tier name |
+| `getTierColor(tier)` | function | Get hex color for a tier |
+| `getTierMinScore(tier)` | function | Get minimum score required for a tier |
+| `getTierMaxScore(tier)` | function | Get maximum score for a tier |
+| `getTierCode(tier)` | function | Get short code string (e.g. "T4") |
+| `meetsTierRequirement(score, minTier)` | function | Check if a score meets a minimum tier |
+| `parseTier(input)` | function | Parse tier from string ("T3", "3", "MONITORED") |
+| `ALL_TIERS` | const | Ordered array of all 8 tiers |
+| `TierThreshold` | type | Interface for tier threshold configuration |
+| `TrustTierName` | type | Union of tier display names |
+| `TrustTierCode` | type | Union of tier short codes ("T0" through "T7") |
+
+### Domains (`@vorionsys/shared-constants/domains`)
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `VORION_DOMAINS` | const | Vorion organization URLs (main, basis, carId, atsf, learn, kaizen) |
+| `AGENTANCHOR_DOMAINS` | const | Agent Anchor AI URLs (main, trust, logic, status, verify) |
+| `COGNIGATE_DOMAINS` | const | Cognigate URLs (main, docs) |
+| `API_ENDPOINTS` | const | Production/staging/sandbox API base URLs |
+| `VORION_EMAILS` | const | Vorion contact email addresses |
+| `AGENTANCHOR_EMAILS` | const | Vorion platform contact email addresses |
+| `GITHUB` | const | GitHub organization and repo URLs |
+| `NPM_PACKAGES` | const | npm package names for all published packages |
+| `ALL_DOMAINS` | const | Combined object containing all domain groups |
+| `DOMAIN_ALIASES` | const | Map of alternate domains to their primary |
+| `VorionDomain` | type | Key union for `VORION_DOMAINS` |
+| `AgentAnchorDomain` | type | Key union for `AGENTANCHOR_DOMAINS` (legacy name) |
+| `CognigateDomain` | type | Key union for `COGNIGATE_DOMAINS` |
+
+### Capabilities (`@vorionsys/shared-constants/capabilities`)
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `CapabilityCategory` | enum | Capability categories (DATA_ACCESS, API_ACCESS, CODE_EXECUTION, etc.) |
+| `CAPABILITIES` | const | Array of all capability definitions with tier gates |
+| `getCapabilitiesForTier(tier)` | function | Get all capabilities available at or below a tier |
+| `getCapability(code)` | function | Look up a capability by its code string |
+| `isCapabilityAvailable(code, tier)` | function | Check if a capability is unlocked at a tier |
+| `getCapabilityMinTier(code)` | function | Get the minimum tier required for a capability |
+| `getCapabilitiesByCategory(category)` | function | Filter capabilities by category |
+| `getAllCapabilityCodes()` | function | Get array of all capability code strings |
+| `CapabilityDefinition` | type | Interface for a capability definition |
+
+### Products (`@vorionsys/shared-constants/products`)
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `ProductCategory` | enum | Product categories (OPEN_SOURCE, COMMERCIAL, DEVELOPER_TOOLS, EDUCATION) |
+| `ProductStatus` | enum | Product lifecycle status (DEVELOPMENT through EOL) |
+| `VORION_PRODUCTS` | const | Vorion open-source product definitions |
+| `AGENTANCHOR_PRODUCTS` | const | Vorion commercial product definitions (legacy name) |
+| `ALL_PRODUCTS` | const | Combined product catalog |
+| `getProduct(id)` | function | Look up a product by ID |
+| `getProductsByCategory(category)` | function | Filter products by category |
+| `getProductsByStatus(status)` | function | Filter products by lifecycle status |
+| `getProductsByOrganization(org)` | function | Get products for "vorion" or "agentanchor" |
+| `ProductDefinition` | type | Interface for a product definition |
+
+### Rate Limits (`@vorionsys/shared-constants/rate-limits`)
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `RATE_LIMITS` | const | Rate-limit configurations keyed by tier |
+| `TIER_QUOTAS` | const | Monthly quota configurations keyed by tier |
+| `getRateLimits(tier)` | function | Get `RateLimitConfig` for a tier |
+| `getMinTierForLimits(config)` | function | Find the lowest tier that satisfies given limits |
+| `wouldExceedLimit(tier, window, count)` | function | Check if a count exceeds a tier's limit for a time window |
+| `formatRateLimit(tier)` | function | Human-readable rate-limit string |
+| `getQuota(tier)` | function | Get `QuotaConfig` for a tier |
+| `isUnlimited(value)` | function | Check if a quota value represents unlimited (-1) |
+| `RateLimitConfig` | type | Interface for rate-limit settings |
+| `QuotaConfig` | type | Interface for monthly quota settings |
+
+### Error Codes (`@vorionsys/shared-constants/error-codes`)
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `ErrorCategory` | enum | Error categories (AUTH, VALIDATION, RATE_LIMIT, NOT_FOUND, TRUST, SERVER, EXTERNAL, CONFIG) |
+| `AUTH_ERRORS` | const | Authentication error definitions (E1001-E1007) |
+| `VALIDATION_ERRORS` | const | Validation error definitions (E2001-E2008) |
+| `RATE_LIMIT_ERRORS` | const | Rate-limit error definitions (E3001-E3004) |
+| `NOT_FOUND_ERRORS` | const | Not-found error definitions (E4001-E4005) |
+| `TRUST_ERRORS` | const | Trust/governance error definitions (E5001-E5007) |
+| `SERVER_ERRORS` | const | Server error definitions (E6001-E6004) |
+| `EXTERNAL_ERRORS` | const | External service error definitions (E7001-E7003) |
+| `ERROR_CODES` | const | All error definitions merged into one object |
+| `getErrorByCode(code)` | function | Look up error by code string (e.g. "E1001") |
+| `getErrorsByCategory(category)` | function | Get all errors in a category |
+| `getRetryableErrors()` | function | Get all errors marked as retryable |
+| `formatErrorMessage(error, params)` | function | Interpolate parameters into a message template |
+| `createErrorResponse(error, params?, requestId?)` | function | Build a structured error response object |
+| `ErrorDefinition` | type | Interface for an error definition |
+| `ErrorCode` | type | Union of all error constant keys |
+
+### API Versions (`@vorionsys/shared-constants/api-versions`)
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `VersionStatus` | enum | Version lifecycle status (DEVELOPMENT, PREVIEW, STABLE, DEPRECATED, RETIRED) |
+| `COGNIGATE_VERSIONS` | const | Cognigate API version definitions |
+| `COGNIGATE_CURRENT_VERSION` | const | Current Cognigate API version string |
+| `COGNIGATE_DEFAULT_VERSION` | const | Default Cognigate API version string |
+| `TRUST_API_VERSIONS` | const | Trust API version definitions |
+| `TRUST_CURRENT_VERSION` | const | Current Trust API version string |
+| `LOGIC_API_VERSIONS` | const | Logic API version definitions |
+| `LOGIC_CURRENT_VERSION` | const | Current Logic API version string |
+| `BASIS_VERSIONS` | const | BASIS spec version definitions |
+| `BASIS_CURRENT_VERSION` | const | Current BASIS spec version string |
+| `BASIS_SPEC_VERSION` | const | Full semver of BASIS spec ("1.0.0") |
+| `CAR_SPEC_VERSIONS` | const | CAR Spec version definitions |
+| `CAR_SPEC_CURRENT_VERSION` | const | Current CAR Spec version string |
+| `API_VERSIONS` | const | All API version definitions grouped by service |
+| `getCurrentVersion(service)` | function | Get current version for a service |
+| `getVersionDefinition(service, version)` | function | Get full version definition |
+| `isVersionSupported(service, version)` | function | Check if a version is still supported |
+| `isVersionDeprecated(service, version)` | function | Check if a version is deprecated |
+| `getStableVersions(service)` | function | Get all stable versions for a service |
+| `buildApiUrl(baseUrl, version, path)` | function | Build a versioned API URL |
+| `VERSION_HEADERS` | const | Standard HTTP header names for version negotiation |
+| `ApiVersionDefinition` | type | Interface for an API version definition |
+
+### Themes (`@vorionsys/shared-constants/themes`)
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `ACTIVE_THEME` | const | Currently active theme ID |
+| `THEMES` | const | All theme token definitions keyed by `ThemeId` |
+| `getActiveTheme()` | function | Get token object for the active theme |
+| `getAllThemeIds()` | function | Get array of all available theme IDs |
+| `themeToCssVars(themeId?)` | function | Generate CSS custom-property string for a theme |
+| `ThemeId` | type | Union of theme identifiers |
+| `ThemeTokens` | type | Interface for a complete set of theme tokens |
+
+### Root Exports
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `VERSION` | const | Package version string |
+| `LAST_UPDATED` | const | Last updated date string |
+
 ## TypeScript
 
-All types are fully exported:
+All types are fully exported and can be imported as type-only:
 
 ```typescript
 import type {
@@ -115,15 +468,36 @@ import type {
   TrustTierName,
   TrustTierCode,
   CapabilityDefinition,
+  CapabilityCategory,
   ProductDefinition,
+  ProductCategory,
+  ProductStatus,
   RateLimitConfig,
+  QuotaConfig,
   ErrorDefinition,
   ErrorCode,
+  ErrorCategory,
   ApiVersionDefinition,
+  VersionStatus,
+  ThemeId,
   ThemeTokens,
+  VorionDomain,
+  AgentAnchorDomain,
+  CognigateDomain,
 } from '@vorionsys/shared-constants';
 ```
 
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.7 (for type-only imports)
+
+## Repository
+
+This package lives in the Vorion monorepo:
+
+[https://github.com/vorionsys/vorion/tree/master/packages/shared-constants](https://github.com/vorionsys/vorion/tree/master/packages/shared-constants)
+
 ## License
 
-MIT
+Apache-2.0

package/dist/api-versions.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @vorionsys/shared-constants - API Versions
+ *
+ * Centralized API version management across all services
+ * Ensures consistent versioning strategy
+ *
+ * @see https://cognigate.dev/docs/versioning
+ */
+declare enum VersionStatus {
+    /** Currently in development, not available */
+    DEVELOPMENT = "development",
+    /** Available as preview/beta */
+    PREVIEW = "preview",
+    /** Stable and recommended */
+    STABLE = "stable",
+    /** Still supported but deprecated */
+    DEPRECATED = "deprecated",
+    /** No longer supported */
+    RETIRED = "retired"
+}
+interface ApiVersionDefinition {
+    /** Version identifier (e.g., "v1") */
+    version: string;
+    /** Full version number (e.g., "1.0.0") */
+    fullVersion: string;
+    /** Release date */
+    releaseDate: string;
+    /** End of support date (if deprecated/retired) */
+    endOfLife?: string;
+    /** Current status */
+    status: VersionStatus;
+    /** Changelog URL */
+    changelogUrl?: string;
+    /** Migration guide URL (if deprecated) */
+    migrationUrl?: string;
+}
+declare const COGNIGATE_VERSIONS: Record<string, ApiVersionDefinition>;
+declare const COGNIGATE_CURRENT_VERSION = "v1";
+declare const COGNIGATE_DEFAULT_VERSION = "v1";
+declare const TRUST_API_VERSIONS: Record<string, ApiVersionDefinition>;
+declare const TRUST_CURRENT_VERSION = "v1";
+declare const LOGIC_API_VERSIONS: Record<string, ApiVersionDefinition>;
+declare const LOGIC_CURRENT_VERSION = "v1";
+declare const BASIS_VERSIONS: Record<string, ApiVersionDefinition>;
+declare const BASIS_CURRENT_VERSION = "v1";
+declare const BASIS_SPEC_VERSION = "1.0.0";
+declare const CAR_SPEC_VERSIONS: Record<string, ApiVersionDefinition>;
+declare const CAR_SPEC_CURRENT_VERSION = "v1";
+declare const API_VERSIONS: {
+    readonly cognigate: Record<string, ApiVersionDefinition>;
+    readonly trust: Record<string, ApiVersionDefinition>;
+    readonly logic: Record<string, ApiVersionDefinition>;
+    readonly basis: Record<string, ApiVersionDefinition>;
+    readonly carSpec: Record<string, ApiVersionDefinition>;
+};
+/**
+ * Get the current stable version for a service
+ */
+declare function getCurrentVersion(service: 'cognigate' | 'trust' | 'logic' | 'basis' | 'carSpec'): string;
+/**
+ * Get version definition
+ */
+declare function getVersionDefinition(service: 'cognigate' | 'trust' | 'logic' | 'basis' | 'carSpec', version: string): ApiVersionDefinition | undefined;
+/**
+ * Check if a version is still supported
+ */
+declare function isVersionSupported(service: 'cognigate' | 'trust' | 'logic' | 'basis' | 'carSpec', version: string): boolean;
+/**
+ * Check if a version is deprecated
+ */
+declare function isVersionDeprecated(service: 'cognigate' | 'trust' | 'logic' | 'basis' | 'carSpec', version: string): boolean;
+/**
+ * Get all stable versions for a service
+ */
+declare function getStableVersions(service: 'cognigate' | 'trust' | 'logic' | 'basis' | 'carSpec'): ApiVersionDefinition[];
+/**
+ * Build versioned API URL
+ */
+declare function buildApiUrl(baseUrl: string, version: string, path: string): string;
+declare const VERSION_HEADERS: {
+    /** Header to request specific API version */
+    readonly REQUEST_VERSION: "X-API-Version";
+    /** Header indicating actual API version used */
+    readonly RESPONSE_VERSION: "X-API-Version";
+    /** Header warning about deprecation */
+    readonly DEPRECATION_WARNING: "X-Deprecation-Warning";
+    /** Header with sunset date */
+    readonly SUNSET: "Sunset";
+};
+
+export { API_VERSIONS, type ApiVersionDefinition, BASIS_CURRENT_VERSION, BASIS_SPEC_VERSION, BASIS_VERSIONS, CAR_SPEC_CURRENT_VERSION, CAR_SPEC_VERSIONS, COGNIGATE_CURRENT_VERSION, COGNIGATE_DEFAULT_VERSION, COGNIGATE_VERSIONS, LOGIC_API_VERSIONS, LOGIC_CURRENT_VERSION, TRUST_API_VERSIONS, TRUST_CURRENT_VERSION, VERSION_HEADERS, VersionStatus, buildApiUrl, getCurrentVersion, getStableVersions, getVersionDefinition, isVersionDeprecated, isVersionSupported };

package/dist/capabilities.cjs

@@ -32,12 +32,13 @@ __export(capabilities_exports, {
 module.exports = __toCommonJS(capabilities_exports);
 var CapabilityCategory = /* @__PURE__ */ ((CapabilityCategory2) => {
   CapabilityCategory2["DATA_ACCESS"] = "data_access";
+  CapabilityCategory2["FILE_OPERATIONS"] = "file_operations";
   CapabilityCategory2["API_ACCESS"] = "api_access";
   CapabilityCategory2["CODE_EXECUTION"] = "code_execution";
   CapabilityCategory2["AGENT_INTERACTION"] = "agent_interaction";
   CapabilityCategory2["RESOURCE_MANAGEMENT"] = "resource_management";
+  CapabilityCategory2["SYSTEM_ADMINISTRATION"] = "system_administration";
   CapabilityCategory2["GOVERNANCE"] = "governance";
-  CapabilityCategory2["ADMIN"] = "admin";
   return CapabilityCategory2;
 })(CapabilityCategory || {});
 var CAPABILITIES = [
@@ -77,7 +78,7 @@ var CAPABILITIES = [
   {
     code: "CAP-FILE-WRITE",
     name: "Write Files",
-    category: "data_access" /* DATA_ACCESS */,
+    category: "file_operations" /* FILE_OPERATIONS */,
     description: "Write to approved directories",
     unlockTier: 2 /* T2_PROVISIONAL */,
     constraints: ["Approved dirs only", "Size limited"]
@@ -193,7 +194,7 @@ var CAPABILITIES = [
   {
     code: "CAP-FULL-ADMIN",
     name: "Full Administration",
-    category: "admin" /* ADMIN */,
+    category: "system_administration" /* SYSTEM_ADMINISTRATION */,
     description: "Full administrative access",
     unlockTier: 7 /* T7_AUTONOMOUS */
   },