byterover-cli 1.0.4 → 1.0.5

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,31 +42,33 @@ 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, subtopic?: string): string;
+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
+ * @returns Normalized relation path without @ prefix (file extension preserved)
  *
  * @example
  * ```ts
- * normalizeRelation('code_style/error-handling') // 'code_style/error-handling'
- * normalizeRelation('@code_style/error-handling') // 'code_style/error-handling'
+ * 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/title.md') // 'code_style/error-handling/title.md'
+ * normalizeRelation('code_style/error-handling/file.md') // 'code_style/error-handling/file.md'
  * ```
  */
 export declare function normalizeRelation(relation: string): string;
@@ -95,8 +81,8 @@ export declare function normalizeRelation(relation: string): 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([])
  * // => ''

package/dist/core/domain/knowledge/relation-parser.js

@@ -1,15 +1,15 @@
 /**
  * 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
  */
 /**
  * Regular expression to match relation paths in markdown content.
- * Matches: @domain/topic or @domain/topic/subtopic
+ * Matches: @domain/topic/title.md or @domain/topic/subtopic/title.md
  */
-const RELATION_PATTERN = /@([\w-]+)\/([\w-]+)(?:\/([\w-]+))?/g;
+const RELATION_PATTERN = /@([\w-]+\/[\w-]+(?:\/[\w-]+)?\/[\w-]+(?:\.[\w]+)?)(?![\w/-])/g;
 /**
- * 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)
@@ -18,104 +18,77 @@ const RELATION_PATTERN = /@([\w-]+)\/([\w-]+)(?:\/([\w-]+))?/g;
  * ```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 function parseRelations(content) {
     const relations = new Set();
-    // Extract all @domain/topic or @domain/topic/subtopic patterns
+    // Extract all @domain/topic/title.md or @domain/topic/subtopic/title.md patterns
     const matches = content.matchAll(RELATION_PATTERN);
     for (const match of matches) {
-        const [, domain, topic, subtopic] = match;
-        const relation = subtopic
-            ? `${domain}/${topic}/${subtopic}`
-            : `${domain}/${topic}`;
-        relations.add(relation);
+        const [, fullPath] = match;
+        relations.add(fullPath.trim());
     }
     return [...relations];
 }
-/**
- * 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 function validateRelationPath(path) {
-    const parts = path.split('/');
-    // Must have 2 or 3 parts: domain/topic or domain/topic/subtopic
-    if (parts.length < 2 || parts.length > 3) {
-        return false;
-    }
-    // Each part must be non-empty and contain only valid characters
-    const validPartPattern = /^[\w-]+$/;
-    return parts.every(part => validPartPattern.test(part));
-}
 /**
  * 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 function resolveRelationPath(basePath, relation) {
-    const parts = relation.split('/');
-    return `${basePath}/${parts.join('/')}/context.md`;
+    return `${basePath}/${relation}`;
 }
 /**
  * Format a relation path using @ notation.
  *
  * @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 function formatRelation(domain, topic, subtopic) {
+export function formatRelation(domain, topic, title, subtopic) {
     return subtopic
-        ? `@${domain}/${topic}/${subtopic}`
-        : `@${domain}/${topic}`;
+        ? `@${domain}/${topic}/${subtopic}/${title}`
+        : `@${domain}/${topic}/${title}`;
 }
 /**
  * Normalize a relation path by removing the @ prefix.
+ * Preserves file extensions (e.g., .md).
  *
  * @param relation - Relation path to normalize
- * @returns Normalized relation path
+ * @returns Normalized relation path without @ prefix (file extension preserved)
  *
  * @example
  * ```ts
- * normalizeRelation('code_style/error-handling') // 'code_style/error-handling'
- * normalizeRelation('@code_style/error-handling') // 'code_style/error-handling'
+ * 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/title.md') // 'code_style/error-handling/title.md'
+ * normalizeRelation('code_style/error-handling/file.md') // 'code_style/error-handling/file.md'
  * ```
  */
 export function normalizeRelation(relation) {
@@ -130,8 +103,8 @@ export function normalizeRelation(relation) {
  *
  * @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([])
  * // => ''
@@ -142,7 +115,12 @@ export function generateRelationsSection(relations) {
         return '';
     }
     const formattedRelations = relations
-        .map(rel => `@${normalizeRelation(rel)}`)
+        .map(rel => {
+        const normalized = normalizeRelation(rel);
+        // Ensure .md extension is present
+        const withExtension = normalized.endsWith('.md') ? normalized : `${normalized}.md`;
+        return `@${withExtension}`;
+    })
         .join('\n');
     return `\n## Relations\n${formattedRelations}\n`;
 }

package/dist/core/domain/transport/schemas.d.ts

@@ -429,6 +429,8 @@ export declare const TransportLlmEventList: readonly ["llmservice:thinking", "ll
 export declare const TransportAgentEventNames: {
     readonly CONNECTED: "agent:connected";
     readonly DISCONNECTED: "agent:disconnected";
+    readonly NEW_SESSION: "agent:newSession";
+    readonly NEW_SESSION_CREATED: "agent:newSessionCreated";
     readonly REGISTER: "agent:register";
     readonly RESTART: "agent:restart";
     readonly RESTARTED: "agent:restarted";
@@ -449,10 +451,10 @@ export declare const TransportSessionEventNames: {
  * Internal message, not exposed to external clients
  */
 export declare const TaskExecuteSchema: z.ZodObject<{
-    /** Client ID that created the task (for response routing) */
-    clientId: z.ZodString;
     /** Client's working directory for file validation */
     clientCwd: z.ZodOptional<z.ZodString>;
+    /** Client ID that created the task (for response routing) */
+    clientId: z.ZodString;
     /** Task content/prompt */
     content: z.ZodString;
     /** Optional file paths for curate --files */
@@ -1137,6 +1139,37 @@ export declare const AgentRestartResponseSchema: z.ZodObject<{
     success: boolean;
     error?: string | undefined;
 }>;
+/**
+ * Request to create a new session (end current, start fresh).
+ * Used by /new command to start a fresh conversation.
+ */
+export declare const AgentNewSessionRequestSchema: z.ZodObject<{
+    /** Optional reason for new session (for logging) */
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    reason?: string | undefined;
+}, {
+    reason?: string | undefined;
+}>;
+/**
+ * Response after new session is created.
+ */
+export declare const AgentNewSessionResponseSchema: z.ZodObject<{
+    /** Error message if session creation failed */
+    error: z.ZodOptional<z.ZodString>;
+    /** The new session ID */
+    sessionId: z.ZodOptional<z.ZodString>;
+    /** Whether the new session was created successfully */
+    success: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    error?: string | undefined;
+    sessionId?: string | undefined;
+}, {
+    success: boolean;
+    error?: string | undefined;
+    sessionId?: string | undefined;
+}>;
 export type TodoItem = z.infer<typeof TodoItemSchema>;
 export type ChunkPayload = z.infer<typeof ChunkPayloadSchema>;
 export type ResponsePayload = z.infer<typeof ResponsePayloadSchema>;
@@ -1163,3 +1196,5 @@ export type SessionSwitchResponse = z.infer<typeof SessionSwitchResponseSchema>;
 export type SessionSwitchedBroadcast = z.infer<typeof SessionSwitchedBroadcastSchema>;
 export type AgentRestartRequest = z.infer<typeof AgentRestartRequestSchema>;
 export type AgentRestartResponse = z.infer<typeof AgentRestartResponseSchema>;
+export type AgentNewSessionRequest = z.infer<typeof AgentNewSessionRequestSchema>;
+export type AgentNewSessionResponse = z.infer<typeof AgentNewSessionResponseSchema>;