byterover-cli 1.0.3 → 1.0.5

package/dist/core/domain/cipher/session/session-metadata.js

@@ -0,0 +1,147 @@
+/**
+ * Session Metadata Types and Schemas
+ *
+ * Defines the data structures for persistent session management.
+ * Sessions are stored in .brv/sessions/ directory as JSON files.
+ *
+ * Design adapted from gemini-cli's ChatRecordingService pattern.
+ */
+import { z } from 'zod';
+// ============================================================================
+// Zod Schemas for Validation
+// ============================================================================
+/**
+ * Schema for ActiveSessionPointer validation.
+ */
+export const ActiveSessionPointerSchema = z.object({
+    activatedAt: z.string().datetime({ offset: true }).or(z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)),
+    pid: z.number().int().positive(),
+    // Optional for backward compatibility with existing session files (treated as stale if missing)
+    processToken: z.string().optional(),
+    sessionId: z.string().min(1),
+});
+/**
+ * Schema for SessionMetadata validation.
+ */
+export const SessionMetadataSchema = z.object({
+    createdAt: z.string().datetime({ offset: true }).or(z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)),
+    lastUpdated: z.string().datetime({ offset: true }).or(z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)),
+    messageCount: z.number().int().nonnegative(),
+    sessionId: z.string().min(1),
+    status: z.enum(['active', 'ended', 'interrupted']),
+    summary: z.string().optional(),
+    title: z.string().optional(),
+    workingDirectory: z.string().min(1),
+});
+// ============================================================================
+// Constants
+// ============================================================================
+/** Prefix for session metadata files */
+export const SESSION_FILE_PREFIX = 'session-';
+/** Directory name for session storage */
+export const SESSIONS_DIR = 'sessions';
+/** Filename for active session pointer */
+export const ACTIVE_SESSION_FILE = 'active.json';
+/** Default session retention config */
+export const DEFAULT_SESSION_RETENTION = {
+    /** Maximum age in days before auto-cleanup */
+    maxAgeDays: 30,
+    /** Maximum number of sessions to keep */
+    maxCount: 50,
+    /** Run cleanup on startup */
+    runOnStartup: true,
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Generate a session filename from timestamp and session ID.
+ *
+ * @param sessionId - The session UUID
+ * @returns Filename in format: session-YYYY-MM-DDTHH-MM-SS-<uuid-prefix>.json
+ */
+export function generateSessionFilename(sessionId) {
+    const timestamp = new Date().toISOString().slice(0, 19).replaceAll(':', '-');
+    const uuidPrefix = sessionId.slice(0, 8);
+    return `${SESSION_FILE_PREFIX}${timestamp}-${uuidPrefix}.json`;
+}
+/**
+ * Parse a session filename to extract timestamp and UUID prefix.
+ *
+ * @param filename - The session filename
+ * @returns Parsed components or null if invalid format
+ */
+export function parseSessionFilename(filename) {
+    if (!filename.startsWith(SESSION_FILE_PREFIX) || !filename.endsWith('.json')) {
+        return null;
+    }
+    // Remove prefix and .json suffix
+    const withoutPrefix = filename.slice(SESSION_FILE_PREFIX.length, -5);
+    // Format: YYYY-MM-DDTHH-MM-SS-<uuid-prefix>
+    // The UUID prefix is the last 8 characters after the last dash
+    const lastDashIndex = withoutPrefix.lastIndexOf('-');
+    if (lastDashIndex === -1) {
+        return null;
+    }
+    const timestamp = withoutPrefix.slice(0, lastDashIndex);
+    const uuidPrefix = withoutPrefix.slice(lastDashIndex + 1);
+    if (uuidPrefix.length !== 8) {
+        return null;
+    }
+    return { timestamp, uuidPrefix };
+}
+/**
+ * Format a timestamp as relative time.
+ *
+ * @param timestamp - ISO timestamp string
+ * @param style - 'long' (e.g., "2 hours ago") or 'short' (e.g., "2h")
+ * @returns Formatted relative time string
+ */
+export function formatRelativeTime(timestamp, style = 'long') {
+    const now = new Date();
+    const time = new Date(timestamp);
+    const diffMs = now.getTime() - time.getTime();
+    const diffSeconds = Math.floor(diffMs / 1000);
+    const diffMinutes = Math.floor(diffSeconds / 60);
+    const diffHours = Math.floor(diffMinutes / 60);
+    const diffDays = Math.floor(diffHours / 24);
+    if (style === 'short') {
+        if (diffSeconds < 1)
+            return 'now';
+        if (diffSeconds < 60)
+            return `${diffSeconds}s`;
+        if (diffMinutes < 60)
+            return `${diffMinutes}m`;
+        if (diffHours < 24)
+            return `${diffHours}h`;
+        if (diffDays < 30)
+            return `${diffDays}d`;
+        const diffMonths = Math.floor(diffDays / 30);
+        return diffMonths < 12 ? `${diffMonths}mo` : `${Math.floor(diffMonths / 12)}y`;
+    }
+    if (diffDays > 0) {
+        return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
+    }
+    if (diffHours > 0) {
+        return `${diffHours} hour${diffHours === 1 ? '' : 's'} ago`;
+    }
+    if (diffMinutes > 0) {
+        return `${diffMinutes} minute${diffMinutes === 1 ? '' : 's'} ago`;
+    }
+    return 'Just now';
+}
+/**
+ * Clean and sanitize message content for display.
+ * Converts newlines to spaces, collapses whitespace, removes non-printable chars.
+ *
+ * @param message - Raw message content
+ * @returns Cleaned message suitable for display
+ */
+export function cleanMessageForTitle(message) {
+    return message
+        .replaceAll(/\n+/g, ' ')
+        .replaceAll(/\s+/g, ' ')
+        .replaceAll(/[^\u0020-\u007E]+/g, '') // Remove non-printable ASCII
+        .trim()
+        .slice(0, 100); // Limit length for title
+}

package/dist/core/domain/entities/auth-token.js

@@ -24,9 +24,12 @@ export class AuthToken {
      * @returns An instance of AuthToken, or undefined if required fields are missing
      */
     static fromJson(json) {
-        // Validate that new required fields exist (for backward compatibility with old tokens)
-        if (!json.userId || !json.userEmail) {
-            return undefined;
+        // Validate ALL required fields exist (prevents corrupted/incomplete tokens from being loaded)
+        const requiredFields = ['accessToken', 'expiresAt', 'refreshToken', 'sessionKey', 'userEmail', 'userId'];
+        for (const field of requiredFields) {
+            if (!json[field]) {
+                return undefined;
+            }
         }
         return new AuthToken({
             accessToken: json.accessToken,

package/dist/core/domain/entities/event.d.ts

@@ -1,7 +1,7 @@
 /**
  * Array of all supported Events.
  */
-export declare const EVENT_VALUES: readonly ["repl", "auth:sign_in", "auth:signed_out", "space:init", "space:changed", "rule:generate", "mem:status", "mem:curate", "mem:pull", "mem:push", "mem:query", "onboarding:init_completed", "onboarding:curate_completed", "onboarding:query_completed", "onboarding:skipped", "onboarding:completed", "init"];
+export declare const EVENT_VALUES: readonly ["repl", "auth:sign_in", "auth:signed_out", "auth:token_invalid", "space:init", "space:changed", "rule:generate", "mem:status", "mem:curate", "mem:pull", "mem:push", "mem:query", "onboarding:init_completed", "onboarding:curate_completed", "onboarding:query_completed", "onboarding:skipped", "onboarding:completed", "init"];
 export type EventName = (typeof EVENT_VALUES)[number];
 export interface PropertyDict {
     [key: string]: any;

package/dist/core/domain/entities/event.js

@@ -5,6 +5,7 @@ export const EVENT_VALUES = [
     'repl',
     'auth:sign_in',
     'auth:signed_out',
+    'auth:token_invalid',
     'space:init',
     'space:changed',
     'rule:generate',
@@ -18,5 +19,5 @@ export const EVENT_VALUES = [
     'onboarding:query_completed',
     'onboarding:skipped',
     'onboarding:completed',
-    'init'
+    'init',
 ];

package/dist/core/domain/knowledge/markdown-writer.d.ts

@@ -1,27 +1,24 @@
-/**
- * Context data for generating context.md files.
- */
+export interface RawConcept {
+    changes?: string[];
+    files?: string[];
+    flow?: string;
+    task?: string;
+    timestamp?: string;
+}
+export interface Narrative {
+    dependencies?: string;
+    features?: string;
+    structure?: string;
+}
 export interface ContextData {
     name: string;
+    narrative?: Narrative;
+    rawConcept?: RawConcept;
     relations?: string[];
     snippets: string[];
 }
-/**
- * Generates Markdown files for knowledge context.
- */
 export declare const MarkdownWriter: {
-    /**
-     * Generate context.md content with snippets and optional relations.
-     * Used for both topics and subtopics in the knowledge hierarchy.
-     */
     generateContext(data: ContextData): string;
-    /**
-     * Merge two context.md contents into one.
-     * Combines snippets and relations, deduplicating where possible.
-     *
-     * @param sourceContent - Raw content from source context.md
-     * @param targetContent - Raw content from target context.md
-     * @returns Merged context.md content
-     */
     mergeContexts(sourceContent: string, targetContent: string): string;
+    parseContent(content: string, name?: string): ContextData;
 };

package/dist/core/domain/knowledge/markdown-writer.js

@@ -1,16 +1,130 @@
 import { generateRelationsSection, parseRelations } from './relation-parser.js';
-/**
- * Extract snippets from context.md content.
- * Removes relations section and splits by separator.
- */
+function generateRawConceptSection(rawConcept) {
+    if (!rawConcept) {
+        return '';
+    }
+    const parts = [];
+    if (rawConcept.task) {
+        parts.push(`**Task:**\n${rawConcept.task}`);
+    }
+    if (rawConcept.changes && rawConcept.changes.length > 0) {
+        parts.push(`**Changes:**\n${rawConcept.changes.map(c => `- ${c}`).join('\n')}`);
+    }
+    if (rawConcept.files && rawConcept.files.length > 0) {
+        parts.push(`**Files:**\n${rawConcept.files.map(f => `- ${f}`).join('\n')}`);
+    }
+    if (rawConcept.flow) {
+        parts.push(`**Flow:**\n${rawConcept.flow}`);
+    }
+    if (rawConcept.timestamp) {
+        parts.push(`**Timestamp:** ${rawConcept.timestamp}`);
+    }
+    if (parts.length === 0) {
+        return '';
+    }
+    return `\n## Raw Concept\n${parts.join('\n\n')}\n`;
+}
+function generateNarrativeSection(narrative) {
+    if (!narrative) {
+        return '';
+    }
+    const parts = [];
+    if (narrative.structure) {
+        parts.push(`### Structure\n${narrative.structure}`);
+    }
+    if (narrative.dependencies) {
+        parts.push(`### Dependencies\n${narrative.dependencies}`);
+    }
+    if (narrative.features) {
+        parts.push(`### Features\n${narrative.features}`);
+    }
+    if (parts.length === 0) {
+        return '';
+    }
+    return `\n## Narrative\n${parts.join('\n\n')}\n`;
+}
+function parseRawConceptSection(content) {
+    // Forgiving regex: allows optional whitespace after "## Raw Concept"
+    const rawConceptMatch = content.match(/##\s*Raw Concept\s*\n([\s\S]*?)(?=\n##\s|\n---\n|$)/i);
+    if (!rawConceptMatch) {
+        return undefined;
+    }
+    const sectionContent = rawConceptMatch[1];
+    const rawConcept = {};
+    // Forgiving: allows whitespace around "Task:" and after the newline
+    const taskMatch = sectionContent.match(/\*\*\s*Task\s*:\s*\*\*\s*\n([\s\S]*?)(?=\n\*\*|\n##|$)/i);
+    if (taskMatch) {
+        rawConcept.task = taskMatch[1].trim();
+    }
+    const changesMatch = sectionContent.match(/\*\*\s*Changes\s*:\s*\*\*\s*\n([\s\S]*?)(?=\n\*\*|\n##|$)/i);
+    if (changesMatch) {
+        rawConcept.changes = changesMatch[1]
+            .split('\n')
+            .filter(line => line.trim().startsWith('- '))
+            .map(line => line.trim().slice(2));
+    }
+    const filesMatch = sectionContent.match(/\*\*\s*Files\s*:\s*\*\*\s*\n([\s\S]*?)(?=\n\*\*|\n##|$)/i);
+    if (filesMatch) {
+        rawConcept.files = filesMatch[1]
+            .split('\n')
+            .filter(line => line.trim().startsWith('- '))
+            .map(line => line.trim().slice(2));
+    }
+    const flowMatch = sectionContent.match(/\*\*\s*Flow\s*:\s*\*\*\s*\n([\s\S]*?)(?=\n\*\*|\n##|$)/i);
+    if (flowMatch) {
+        rawConcept.flow = flowMatch[1].trim();
+    }
+    // Timestamp can be inline, so more flexible pattern
+    const timestampMatch = sectionContent.match(/\*\*\s*Timestamp\s*:\s*\*\*\s*(.+)/i);
+    if (timestampMatch) {
+        rawConcept.timestamp = timestampMatch[1].trim();
+    }
+    if (Object.keys(rawConcept).length === 0) {
+        return undefined;
+    }
+    return rawConcept;
+}
+function parseNarrativeSection(content) {
+    // Forgiving regex: allows optional whitespace after "## Narrative"
+    const narrativeMatch = content.match(/##\s*Narrative\s*\n([\s\S]*?)(?=\n##\s[^#]|\n---\n|$)/i);
+    if (!narrativeMatch) {
+        return undefined;
+    }
+    const sectionContent = narrativeMatch[1];
+    const narrative = {};
+    // Forgiving: allows whitespace after "### Structure"
+    const structureMatch = sectionContent.match(/###\s*Structure\s*\n([\s\S]*?)(?=\n###\s|\n##\s|$)/i);
+    if (structureMatch) {
+        narrative.structure = structureMatch[1].trim();
+    }
+    const dependenciesMatch = sectionContent.match(/###\s*Dependencies\s*\n([\s\S]*?)(?=\n###\s|\n##\s|$)/i);
+    if (dependenciesMatch) {
+        narrative.dependencies = dependenciesMatch[1].trim();
+    }
+    const featuresMatch = sectionContent.match(/###\s*Features\s*\n([\s\S]*?)(?=\n###\s|\n##\s|$)/i);
+    if (featuresMatch) {
+        narrative.features = featuresMatch[1].trim();
+    }
+    if (Object.keys(narrative).length === 0) {
+        return undefined;
+    }
+    return narrative;
+}
 function extractSnippetsFromContent(content) {
-    // Remove relations section if present
     let snippetContent = content;
-    const relationsMatch = content.match(/## Relations[\s\S]*?(?=\n[^@\n]|$)/);
+    // Forgiving regex patterns for section removal
+    const relationsMatch = content.match(/##\s*Relations[\s\S]*?(?=\n[^@\n]|$)/i);
     if (relationsMatch) {
-        snippetContent = content.replace(relationsMatch[0], '').trim();
+        snippetContent = snippetContent.replace(relationsMatch[0], '').trim();
+    }
+    const rawConceptMatch = snippetContent.match(/##\s*Raw Concept[\s\S]*?(?=\n##\s|\n---\n|$)/i);
+    if (rawConceptMatch) {
+        snippetContent = snippetContent.replace(rawConceptMatch[0], '').trim();
+    }
+    const narrativeMatch = snippetContent.match(/##\s*Narrative[\s\S]*?(?=\n##\s|\n---\n|$)/i);
+    if (narrativeMatch) {
+        snippetContent = snippetContent.replace(narrativeMatch[0], '').trim();
     }
-    // Split by separator and filter empty
     const snippets = snippetContent
         .split(/\n---\n/)
         .map(s => s.trim())
@@ -18,39 +132,112 @@ function extractSnippetsFromContent(content) {
     return snippets;
 }
 /**
- * Generates Markdown files for knowledge context.
+ * Merges two RawConcept objects with the following strategy:
+ *
+ * **Scalars (task, flow, timestamp)**: Source wins (source.X || target.X)
+ * - Rationale: The source represents "new" or "incoming" data that should
+ *   take precedence over existing target data for singular values.
+ *
+ * **Arrays (changes, files)**: Concatenated and deduplicated (target first, then source)
+ * - Rationale: For lists, we want to accumulate all entries rather than
+ *   replacing them. Target entries are placed first to preserve order.
+ *
+ * @param source - The incoming/new RawConcept to merge (takes precedence for scalars)
+ * @param target - The existing/base RawConcept to merge into
+ * @returns Merged RawConcept or undefined if both inputs are empty
  */
+function mergeRawConcepts(source, target) {
+    if (!source && !target) {
+        return undefined;
+    }
+    if (!source)
+        return target;
+    if (!target)
+        return source;
+    const merged = {};
+    // Scalars: source wins (newer data takes precedence)
+    merged.task = source.task || target.task;
+    merged.flow = source.flow || target.flow;
+    merged.timestamp = source.timestamp || target.timestamp;
+    // Arrays: concatenate and deduplicate (target first, then source)
+    const allChanges = [...(target.changes || []), ...(source.changes || [])];
+    if (allChanges.length > 0) {
+        merged.changes = [...new Set(allChanges)];
+    }
+    const allFiles = [...(target.files || []), ...(source.files || [])];
+    if (allFiles.length > 0) {
+        merged.files = [...new Set(allFiles)];
+    }
+    if (Object.keys(merged).length === 0) {
+        return undefined;
+    }
+    return merged;
+}
+function mergeNarratives(source, target) {
+    if (!source && !target) {
+        return undefined;
+    }
+    if (!source)
+        return target;
+    if (!target)
+        return source;
+    const merged = {};
+    if (source.structure || target.structure) {
+        const parts = [target.structure, source.structure].filter(Boolean);
+        merged.structure = parts.join('\n\n');
+    }
+    if (source.dependencies || target.dependencies) {
+        const parts = [target.dependencies, source.dependencies].filter(Boolean);
+        merged.dependencies = parts.join('\n\n');
+    }
+    if (source.features || target.features) {
+        const parts = [target.features, source.features].filter(Boolean);
+        merged.features = parts.join('\n\n');
+    }
+    if (Object.keys(merged).length === 0) {
+        return undefined;
+    }
+    return merged;
+}
 export const MarkdownWriter = {
-    /**
-     * Generate context.md content with snippets and optional relations.
-     * Used for both topics and subtopics in the knowledge hierarchy.
-     */
     generateContext(data) {
-        const snippets = data.snippets || [];
+        const snippets = (data.snippets || []).filter(s => s && s.trim());
         const relations = data.relations || [];
         const relationsSection = generateRelationsSection(relations);
-        return `${relationsSection}
-${snippets.length > 0 ? snippets.map(s => `${s}`).join('\n\n---\n\n') : 'No context available.'}
-`;
+        const rawConceptSection = generateRawConceptSection(data.rawConcept);
+        const narrativeSection = generateNarrativeSection(data.narrative);
+        const hasSnippets = snippets.length > 0;
+        // Build the content parts
+        const parts = [];
+        // Add sections (relations, rawConcept, narrative)
+        const sectionsContent = `${relationsSection}${rawConceptSection}${narrativeSection}`.trim();
+        if (sectionsContent) {
+            parts.push(sectionsContent);
+        }
+        // Add snippets if present
+        if (hasSnippets) {
+            const snippetsContent = snippets.join('\n\n---\n\n');
+            parts.push(snippetsContent);
+        }
+        // If nothing at all, return empty (should not happen in practice)
+        if (parts.length === 0) {
+            return '';
+        }
+        // Join parts with separator only if we have both sections and snippets
+        return parts.join('\n\n---\n\n') + '\n';
     },
-    /**
-     * Merge two context.md contents into one.
-     * Combines snippets and relations, deduplicating where possible.
-     *
-     * @param sourceContent - Raw content from source context.md
-     * @param targetContent - Raw content from target context.md
-     * @returns Merged context.md content
-     */
     mergeContexts(sourceContent, targetContent) {
-        // Extract relations from both contents
         const sourceRelations = parseRelations(sourceContent);
         const targetRelations = parseRelations(targetContent);
-        // Merge and deduplicate relations
         const mergedRelations = [...new Set([...sourceRelations, ...targetRelations])];
+        const sourceRawConcept = parseRawConceptSection(sourceContent);
+        const targetRawConcept = parseRawConceptSection(targetContent);
+        const mergedRawConcept = mergeRawConcepts(sourceRawConcept, targetRawConcept);
+        const sourceNarrative = parseNarrativeSection(sourceContent);
+        const targetNarrative = parseNarrativeSection(targetContent);
+        const mergedNarrative = mergeNarratives(sourceNarrative, targetNarrative);
         const sourceSnippets = extractSnippetsFromContent(sourceContent);
         const targetSnippets = extractSnippetsFromContent(targetContent);
-        // Merge snippets (target first, then source)
-        // Deduplicate by exact match
         const seenSnippets = new Set();
         const mergedSnippets = [];
         for (const snippet of [...targetSnippets, ...sourceSnippets]) {
@@ -59,10 +246,21 @@ ${snippets.length > 0 ? snippets.map(s => `${s}`).join('\n\n---\n\n') : 'No cont
                 mergedSnippets.push(snippet);
             }
         }
-        // Generate merged content
-        const relationsSection = generateRelationsSection(mergedRelations);
-        return `${relationsSection}
-${mergedSnippets.length > 0 ? mergedSnippets.join('\n\n---\n\n') : 'No context available.'}
-`;
+        return MarkdownWriter.generateContext({
+            name: '',
+            narrative: mergedNarrative,
+            rawConcept: mergedRawConcept,
+            relations: mergedRelations,
+            snippets: mergedSnippets,
+        });
+    },
+    parseContent(content, name = '') {
+        return {
+            name,
+            narrative: parseNarrativeSection(content),
+            rawConcept: parseRawConceptSection(content),
+            relations: parseRelations(content),
+            snippets: extractSnippetsFromContent(content),
+        };
     },
 };

package/dist/core/domain/knowledge/relation-parser.d.ts

@@ -1,10 +1,10 @@
 /**
  * Utilities for parsing and managing context relations.
- * Relations are expressed using @ notation: @domain/topic or @domain/topic/subtopic
+ * Relations are expressed using @ notation: @domain/topic/title.md or @domain/topic/subtopic/title.md
  */
 /**
- * Parse relations from context.md content.
- * Extracts all @domain/topic or @domain/topic/subtopic references.
+ * Parse relations from title.md content.
+ * Extracts all @domain/topic/title.md or @domain/topic/subtopic/title.md references.
  *
  * @param content - Markdown content to parse
  * @returns Array of unique relation paths (without @ prefix)
@@ -13,43 +13,27 @@
  * ```ts
  * const content = `
  * ## Relations
- * @code_style/error-handling
- * @structure/api-endpoints
+ * @code_style/error-handling/overview.md
+ * @structure/api/endpoints/rest.md
  * `
- * parseRelations(content) // ['code_style/error-handling', 'structure/api-endpoints']
+ * parseRelations(content) // ['code_style/error-handling/overview.md', 'structure/api/endpoints/rest.md']
  * ```
  */
 export declare function parseRelations(content: string): string[];
-/**
- * Validate a relation path format.
- * Valid formats: domain/topic or domain/topic/subtopic
- *
- * @param path - Relation path to validate (without @ prefix)
- * @returns True if path format is valid
- *
- * @example
- * ```ts
- * validateRelationPath('code_style/error-handling') // true
- * validateRelationPath('code_style/error-handling/try-catch') // true
- * validateRelationPath('invalid') // false
- * validateRelationPath('too/many/parts/here') // false
- * ```
- */
-export declare function validateRelationPath(path: string): boolean;
 /**
  * Resolve a relation path to an absolute file system path.
  *
  * @param basePath - Base path to context tree (e.g., '.brv/context-tree')
- * @param relation - Relation path (e.g., 'domain/topic' or 'domain/topic/subtopic')
- * @returns Absolute path to the context.md file
+ * @param relation - Relation path (e.g., 'domain/topic/title.md' or 'domain/topic/subtopic/title.md')
+ * @returns Absolute path to the title.md file
  *
  * @example
  * ```ts
- * resolveRelationPath('.brv/context-tree', 'code_style/error-handling')
- * // => '.brv/context-tree/code_style/error-handling/context.md'
+ * resolveRelationPath('.brv/context-tree', 'code_style/error-handling/overview.md')
+ * // => '.brv/context-tree/code_style/error-handling/overview.md'
  *
- * resolveRelationPath('.brv/context-tree', 'structure/api/endpoints')
- * // => '.brv/context-tree/structure/api/endpoints/context.md'
+ * resolveRelationPath('.brv/context-tree', 'structure/api/endpoints/rest.md')
+ * // => '.brv/context-tree/structure/api/endpoints/rest.md'
  * ```
  */
 export declare function resolveRelationPath(basePath: string, relation: string): string;
@@ -58,30 +42,47 @@ export declare function resolveRelationPath(basePath: string, relation: string):
  *
  * @param domain - Domain name
  * @param topic - Topic name
+ * @param title - Title (with .md extension)
  * @param subtopic - Optional subtopic name
  * @returns Formatted relation string with @ prefix
  *
  * @example
  * ```ts
- * formatRelation('code_style', 'error-handling')
- * // => '@code_style/error-handling'
+ * formatRelation('code_style', 'error-handling', 'overview.md')
+ * // => '@code_style/error-handling/overview.md'
  *
- * formatRelation('structure', 'api', 'endpoints')
- * // => '@structure/api/endpoints'
+ * formatRelation('structure', 'api', 'endpoints', 'rest.md')
+ * // => '@structure/api/endpoints/rest.md'
+ * ```
+ */
+export declare function formatRelation(domain: string, topic: string, title: string, subtopic?: string): string;
+/**
+ * Normalize a relation path by removing the @ prefix.
+ * Preserves file extensions (e.g., .md).
+ *
+ * @param relation - Relation path to normalize
+ * @returns Normalized relation path without @ prefix (file extension preserved)
+ *
+ * @example
+ * ```ts
+ * normalizeRelation('code_style/error-handling.md') // 'code_style/error-handling.md'
+ * normalizeRelation('@code_style/error-handling.md') // 'code_style/error-handling.md'
+ * normalizeRelation('code_style/error-handling/title.md') // 'code_style/error-handling/title.md'
+ * normalizeRelation('code_style/error-handling/file.md') // 'code_style/error-handling/file.md'
  * ```
  */
-export declare function formatRelation(domain: string, topic: string, subtopic?: string): string;
+export declare function normalizeRelation(relation: string): string;
 /**
  * Generate the Relations section for context.md.
  * Returns empty string if no relations provided.
  *
- * @param relations - Array of relation paths (without @ prefix)
+ * @param relations - Array of relation paths (with or without @ prefix)
  * @returns Markdown formatted Relations section or empty string
  *
  * @example
  * ```ts
- * generateRelationsSection(['code_style/error-handling', 'structure/api'])
- * // => '\n## Relations\n@code_style/error-handling\n@structure/api\n'
+ * generateRelationsSection(['code_style/error-handling/overview.md', 'structure/api/rest.md'])
+ * // => '\n## Relations\n@code_style/error-handling/overview.md\n@structure/api/rest.md\n'
  *
  * generateRelationsSection([])
  * // => ''