@cakemail-org/cakemail-cli 1.5.0 → 2.0.0

package/docs/testing/KENOGAMI_BIDIRECTIONAL_FLOW.md

@@ -0,0 +1,1517 @@
+# Kenogami: Bidirectional Knowledge Graph System
+
+## Overview
+
+Kenogami is a knowledge-base system where the **knowledge graph becomes the source of truth** rather than just a derivative of articles. This inverts the traditional flow from "Articles → Knowledge Graph" to "Knowledge Graph ↔ Articles" with bidirectional synchronization.
+
+---
+
+## Table of Contents
+
+1. [Traditional vs Bidirectional Flow](#traditional-vs-bidirectional-flow)
+2. [Architectural Changes](#architectural-changes)
+3. [Knowledge Graph as Source of Truth](#knowledge-graph-as-source-of-truth)
+4. [Article Generation from Graph](#article-generation-from-graph)
+5. [Synchronization Strategies](#synchronization-strategies)
+6. [Conflict Resolution](#conflict-resolution)
+7. [Implementation Design](#implementation-design)
+8. [User Workflows](#user-workflows)
+9. [Integration with AI Testing](#integration-with-ai-testing)
+
+---
+
+## Traditional vs Bidirectional Flow
+
+### Traditional Flow (Current AI Testing Design)
+
+```
+┌─────────────────┐
+│   Articles      │  (Source of Truth)
+│   (Markdown)    │
+└────────┬────────┘
+         │
+         │ Parse & Extract
+         ▼
+┌─────────────────┐
+│ Knowledge Graph │  (Derived Data)
+│  (Read-Only)    │
+└────────┬────────┘
+         │
+         │ Query
+         ▼
+┌─────────────────┐
+│   AI Testing    │
+│   Validation    │
+└─────────────────┘
+```
+
+**Problems:**
+- ❌ Duplicate content across articles (same command documented in multiple places)
+- ❌ Inconsistent formatting and terminology
+- ❌ Hard to maintain relationships between concepts
+- ❌ No single source of truth for facts
+- ❌ Articles can drift out of sync with each other
+
+### Bidirectional Flow (Kenogami Approach)
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    Knowledge Graph (KG)                       │
+│                   (SOURCE OF TRUTH)                           │
+│                                                               │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
+│  │ Command  │───▶│Parameter │    │ Concept  │              │
+│  │  Node    │    │   Node   │    │   Node   │              │
+│  └──────────┘    └──────────┘    └──────────┘              │
+│       │                                │                     │
+│       │ hasExample                     │ relatesTo           │
+│       ▼                                ▼                     │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
+│  │ Example  │    │   Error  │    │Workflow  │              │
+│  │  Node    │    │   Node   │    │   Node   │              │
+│  └──────────┘    └──────────┘    └──────────┘              │
+└───────┬──────────────────────────────────┬──────────────────┘
+        │                                   │
+        │ Generate                          │ Extract/Update
+        ▼                                   │
+┌─────────────────┐                        │
+│   Articles      │◀───────────────────────┘
+│   (Markdown)    │
+│  (Generated)    │
+└────────┬────────┘
+         │
+         │ Test Against
+         ▼
+┌─────────────────┐
+│   AI Testing    │
+│   Validation    │
+└─────────────────┘
+```
+
+**Benefits:**
+- ✅ Single source of truth (the graph)
+- ✅ Automatic consistency across all articles
+- ✅ Relationships are first-class entities
+- ✅ Generate multiple article views from same data
+- ✅ Update once, reflect everywhere
+- ✅ Track changes at the fact level, not document level
+
+---
+
+## Architectural Changes
+
+### System Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Kenogami System                       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│   Graph      │      │  Article     │      │Sync Engine   │
+│   Editor     │      │  Generator   │      │              │
+│              │      │              │      │              │
+│ - Add nodes  │      │ - Templates  │      │ - Diff       │
+│ - Edit facts │      │ - Rendering  │      │ - Merge      │
+│ - Relations  │      │ - Formatting │      │ - Conflict   │
+└──────┬───────┘      └──────┬───────┘      └──────┬───────┘
+       │                     │                     │
+       │                     │                     │
+       └─────────────────────┼─────────────────────┘
+                             │
+                             ▼
+                  ┌─────────────────┐
+                  │ Knowledge Graph │
+                  │   (Neo4j or     │
+                  │   similar DB)   │
+                  └─────────────────┘
+```
+
+### Data Flow Changes
+
+**Old Flow: Article → Graph**
+```typescript
+// Traditional extraction
+const articles = readMarkdownFiles('./docs');
+const knowledgeGraph = await extractKnowledge(articles);
+// Graph is derivative, articles are source
+```
+
+**New Flow: Graph → Articles**
+```typescript
+// Graph-first approach
+const knowledgeGraph = loadKnowledgeGraph(); // Source of truth
+const articles = await generateArticles(knowledgeGraph, templates);
+// Articles are derivative, graph is source
+```
+
+**Hybrid Flow: Graph ↔ Articles (Recommended)**
+```typescript
+// Bidirectional sync
+const knowledgeGraph = loadKnowledgeGraph();
+
+// When articles are edited by humans:
+const articleChanges = detectChanges('./docs');
+await syncArticlesToGraph(articleChanges, knowledgeGraph);
+
+// When graph is edited programmatically:
+const graphChanges = detectGraphChanges(knowledgeGraph);
+await syncGraphToArticles(graphChanges, './docs', templates);
+```
+
+---
+
+## Knowledge Graph as Source of Truth
+
+### Graph Schema Design
+
+**Node Types:**
+
+```typescript
+type KnowledgeNode =
+  | CommandNode
+  | ConceptNode
+  | ParameterNode
+  | ExampleNode
+  | ErrorNode
+  | WorkflowNode
+  | TutorialNode
+  | FAQNode;
+
+interface CommandNode {
+  id: string;
+  type: 'command';
+  name: string; // "cakemail campaigns list"
+  category: string; // "campaigns"
+  description: string;
+  version_added: string; // "1.3.0"
+  version_deprecated?: string;
+
+  // Metadata
+  aliases: string[];
+  platform: 'cli' | 'web' | 'mobile' | 'api';
+  authentication_required: boolean;
+
+  // Relationships (defined as edges)
+  // → hasParameter → ParameterNode
+  // → hasExample → ExampleNode
+  // → canThrow → ErrorNode
+  // → partOfWorkflow → WorkflowNode
+  // → relatedTo → CommandNode
+  // → documentedIn → ArticleNode
+}
+
+interface ParameterNode {
+  id: string;
+  type: 'parameter';
+  name: string; // "status"
+  flag: string; // "-s, --status"
+  description: string;
+  value_type: 'string' | 'number' | 'boolean' | 'enum';
+  required: boolean;
+  default_value?: any;
+  enum_values?: string[];
+
+  // Relationships
+  // ← hasParameter ← CommandNode
+  // → hasExample → ExampleNode
+  // → validates → ValidationRuleNode
+}
+
+interface ExampleNode {
+  id: string;
+  type: 'example';
+  title: string;
+  command: string; // Full command string
+  description: string;
+  expected_output: string | object;
+  expected_exit_code: number;
+  platform: 'cli' | 'web' | 'mobile';
+
+  // Relationships
+  // ← hasExample ← CommandNode
+  // → producesOutput → OutputNode
+}
+
+interface ConceptNode {
+  id: string;
+  type: 'concept';
+  name: string; // "OAuth Authentication"
+  description: string;
+  category: 'core' | 'advanced' | 'reference';
+
+  // Relationships
+  // → relatedTo → ConceptNode
+  // → implements → CommandNode
+  // → prerequisiteFor → ConceptNode
+  // → documentedIn → ArticleNode
+}
+
+interface WorkflowNode {
+  id: string;
+  type: 'workflow';
+  name: string; // "Create and Send Campaign"
+  description: string;
+  steps: WorkflowStep[];
+
+  // Relationships
+  // → hasStep → CommandNode (ordered)
+  // → requires → ConceptNode
+}
+
+interface ArticleNode {
+  id: string;
+  type: 'article';
+  title: string;
+  slug: string; // "campaigns-management"
+  path: string; // "docs/user-manual/campaigns.md"
+  category: string;
+  template: 'command_reference' | 'tutorial' | 'concept' | 'faq';
+  last_generated: Date;
+  last_human_edit?: Date;
+
+  // Relationships
+  // ← documentedIn ← CommandNode
+  // ← documentedIn ← ConceptNode
+  // → includes → (any node type)
+}
+```
+
+**Relationship Types:**
+
+```cypher
+// Command → Parameter
+(:Command)-[:HAS_PARAMETER {position: 1, required: true}]->(:Parameter)
+
+// Command → Example
+(:Command)-[:HAS_EXAMPLE {order: 1}]->(:Example)
+
+// Command → Error
+(:Command)-[:CAN_THROW {condition: "invalid list ID"}]->(:Error)
+
+// Command → Command (related)
+(:Command)-[:RELATED_TO {similarity: 0.8}]->(:Command)
+
+// Command → Workflow
+(:Command)-[:PART_OF_WORKFLOW {step: 2}]->(:Workflow)
+
+// Concept → Concept (prerequisite)
+(:Concept)-[:PREREQUISITE_FOR]->(:Concept)
+
+// Article → Content (what it documents)
+(:Article)-[:DOCUMENTS {section: "Usage"}]->(:Command)
+
+// Temporal relationships
+(:Command)-[:SUPERSEDES]->(:Command) // v2 command replaces v1
+(:Command)-[:DEPRECATED_IN {version: "2.0.0"}]->(:Version)
+```
+
+### Graph Query Examples
+
+**Find all commands in a category:**
+```cypher
+MATCH (c:Command {category: 'campaigns'})
+RETURN c.name, c.description
+ORDER BY c.name
+```
+
+**Find command with all related information:**
+```cypher
+MATCH (c:Command {name: 'cakemail campaigns list'})
+OPTIONAL MATCH (c)-[:HAS_PARAMETER]->(p:Parameter)
+OPTIONAL MATCH (c)-[:HAS_EXAMPLE]->(e:Example)
+OPTIONAL MATCH (c)-[:CAN_THROW]->(err:Error)
+OPTIONAL MATCH (c)-[:RELATED_TO]->(related:Command)
+RETURN c,
+       collect(DISTINCT p) as parameters,
+       collect(DISTINCT e) as examples,
+       collect(DISTINCT err) as errors,
+       collect(DISTINCT related) as related_commands
+```
+
+**Find all articles that need regeneration:**
+```cypher
+// Find articles where documented commands have changed
+MATCH (a:Article)-[:DOCUMENTS]->(c:Command)
+WHERE c.updated_at > a.last_generated
+RETURN a.path, a.title, count(c) as outdated_commands
+ORDER BY outdated_commands DESC
+```
+
+**Find workflow for a goal:**
+```cypher
+MATCH (w:Workflow {name: 'Create and Send Campaign'})
+MATCH (w)-[s:HAS_STEP]->(c:Command)
+RETURN c.name, s.step
+ORDER BY s.step
+```
+
+---
+
+## Article Generation from Graph
+
+### Template System
+
+**Article Templates:**
+
+```typescript
+interface ArticleTemplate {
+  type: 'command_reference' | 'tutorial' | 'concept' | 'faq';
+  structure: TemplateSection[];
+  renderingRules: RenderingRule[];
+}
+
+interface CommandReferenceTemplate extends ArticleTemplate {
+  type: 'command_reference';
+  structure: [
+    { section: 'title', source: 'command.name' },
+    { section: 'description', source: 'command.description' },
+    { section: 'usage', generator: 'renderUsage' },
+    { section: 'parameters', generator: 'renderParameters' },
+    { section: 'examples', generator: 'renderExamples' },
+    { section: 'errors', generator: 'renderErrors' },
+    { section: 'related', generator: 'renderRelated' }
+  ];
+}
+```
+
+**Template Example (Command Reference):**
+
+```handlebars
+{{!-- templates/command-reference.hbs --}}
+# {{command.name}}
+
+{{command.description}}
+
+## Usage
+
+```bash
+{{command.name}} {{#each parameters}}{{renderParameter this}}{{/each}}
+```
+
+## Parameters
+
+{{#each parameters}}
+### {{flag}}
+
+{{description}}
+
+- **Type:** `{{value_type}}`
+- **Required:** {{#if required}}Yes{{else}}No{{/if}}
+{{#if default_value}}
+- **Default:** `{{default_value}}`
+{{/if}}
+{{#if enum_values}}
+- **Valid values:** {{#each enum_values}}`{{this}}`{{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}
+
+{{/each}}
+
+## Examples
+
+{{#each examples}}
+### {{title}}
+
+```bash
+{{command}}
+```
+
+{{description}}
+
+**Expected output:**
+```{{#if (isJSON expected_output)}}json{{else}}text{{/if}}
+{{expected_output}}
+```
+
+{{/each}}
+
+## Error Handling
+
+{{#each errors}}
+### {{error_message}}
+
+{{description}}
+
+**Exit code:** {{exit_code}}
+
+{{#if suggestion}}
+💡 **Tip:** {{suggestion}}
+{{/if}}
+
+{{/each}}
+
+## Related Commands
+
+{{#each related_commands}}
+- [`{{name}}`]({{link}}) - {{description}}
+{{/each}}
+
+---
+
+*Last generated: {{generated_at}}*
+*Source: Knowledge Graph v{{graph_version}}*
+```
+
+### Article Generator
+
+```typescript
+class ArticleGenerator {
+  constructor(
+    private knowledgeGraph: KnowledgeGraph,
+    private templates: TemplateRegistry
+  ) {}
+
+  async generateArticle(articleId: string): Promise<GeneratedArticle> {
+    // 1. Load article node from graph
+    const articleNode = await this.knowledgeGraph.getNode(articleId);
+
+    // 2. Query all related content
+    const content = await this.queryArticleContent(articleNode);
+
+    // 3. Select template
+    const template = this.templates.get(articleNode.template);
+
+    // 4. Render article
+    const markdown = await this.renderTemplate(template, content);
+
+    // 5. Add metadata
+    const frontmatter = this.generateFrontmatter(articleNode, content);
+
+    return {
+      path: articleNode.path,
+      content: `${frontmatter}\n\n${markdown}`,
+      metadata: {
+        generated_at: new Date(),
+        source_nodes: content.nodes.map(n => n.id),
+        template: articleNode.template
+      }
+    };
+  }
+
+  async queryArticleContent(articleNode: ArticleNode): Promise<ArticleContent> {
+    // Query based on article type
+    switch (articleNode.template) {
+      case 'command_reference':
+        return this.queryCommandReference(articleNode);
+      case 'tutorial':
+        return this.queryTutorial(articleNode);
+      case 'concept':
+        return this.queryConcept(articleNode);
+      case 'faq':
+        return this.queryFAQ(articleNode);
+    }
+  }
+
+  async queryCommandReference(articleNode: ArticleNode): Promise<ArticleContent> {
+    // Cypher query to get all commands documented in this article
+    const query = `
+      MATCH (a:Article {id: $articleId})-[:DOCUMENTS]->(c:Command)
+      OPTIONAL MATCH (c)-[:HAS_PARAMETER]->(p:Parameter)
+      OPTIONAL MATCH (c)-[:HAS_EXAMPLE]->(e:Example)
+      OPTIONAL MATCH (c)-[:CAN_THROW]->(err:Error)
+      OPTIONAL MATCH (c)-[:RELATED_TO]->(rel:Command)
+      RETURN c,
+             collect(DISTINCT p) as parameters,
+             collect(DISTINCT e) as examples,
+             collect(DISTINCT err) as errors,
+             collect(DISTINCT rel) as related
+    `;
+
+    const result = await this.knowledgeGraph.query(query, { articleId: articleNode.id });
+
+    return {
+      commands: result.map(r => ({
+        ...r.c,
+        parameters: r.parameters,
+        examples: r.examples,
+        errors: r.errors,
+        related: r.related
+      }))
+    };
+  }
+
+  generateFrontmatter(articleNode: ArticleNode, content: ArticleContent): string {
+    return `---
+title: ${articleNode.title}
+category: ${articleNode.category}
+template: ${articleNode.template}
+generated_at: ${new Date().toISOString()}
+graph_version: ${this.knowledgeGraph.version}
+source_nodes: [${content.nodes.map(n => n.id).join(', ')}]
+---`;
+  }
+}
+```
+
+### Regeneration Strategies
+
+**Strategy 1: Full Regeneration**
+```typescript
+// Regenerate all articles from scratch
+async function regenerateAllArticles() {
+  const articles = await knowledgeGraph.getAllNodes('Article');
+
+  for (const article of articles) {
+    const generated = await articleGenerator.generateArticle(article.id);
+    await writeFile(generated.path, generated.content);
+
+    // Update article node with generation timestamp
+    await knowledgeGraph.updateNode(article.id, {
+      last_generated: new Date()
+    });
+  }
+}
+```
+
+**Strategy 2: Selective Regeneration (Efficient)**
+```typescript
+// Only regenerate articles affected by graph changes
+async function regenerateChangedArticles(changedNodeIds: string[]) {
+  // Find all articles that document the changed nodes
+  const query = `
+    MATCH (a:Article)-[:DOCUMENTS*1..2]->(n)
+    WHERE n.id IN $changedNodeIds
+    RETURN DISTINCT a
+  `;
+
+  const affectedArticles = await knowledgeGraph.query(query, { changedNodeIds });
+
+  for (const article of affectedArticles) {
+    await articleGenerator.generateArticle(article.id);
+  }
+}
+```
+
+**Strategy 3: Incremental Updates (Advanced)**
+```typescript
+// Update only changed sections of articles
+async function incrementalUpdate(nodeId: string, changes: NodeChanges) {
+  const affectedArticles = await findArticlesDocumenting(nodeId);
+
+  for (const article of affectedArticles) {
+    // Parse existing article
+    const existingContent = await readFile(article.path);
+    const ast = parseMarkdown(existingContent);
+
+    // Find section that documents this node
+    const section = findSectionForNode(ast, nodeId);
+
+    // Regenerate only that section
+    const newSection = await generateSection(nodeId, changes);
+
+    // Replace section in AST
+    ast.replace(section, newSection);
+
+    // Write back
+    await writeFile(article.path, renderMarkdown(ast));
+  }
+}
+```
+
+---
+
+## Synchronization Strategies
+
+### Two-Way Sync Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     Sync Coordinator                          │
+└──────────────────────────────────────────────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│  Change      │      │   Conflict   │      │  Merge       │
+│  Detector    │      │   Resolver   │      │  Engine      │
+└──────────────┘      └──────────────┘      └──────────────┘
+```
+
+### Change Detection
+
+**Article Changes (Human Edits):**
+
+```typescript
+class ArticleChangeDetector {
+  async detectChanges(articlePath: string): Promise<ArticleChanges> {
+    // 1. Parse current article
+    const currentContent = await readFile(articlePath);
+    const currentAST = parseMarkdown(currentContent);
+
+    // 2. Get last known state from graph
+    const articleNode = await this.getArticleNodeByPath(articlePath);
+    const lastGenerated = articleNode.last_generated;
+
+    // 3. Load version from last generation
+    const lastContent = await this.getGeneratedVersion(articleNode.id, lastGenerated);
+    const lastAST = parseMarkdown(lastContent);
+
+    // 4. Diff the two versions
+    const diff = diffAST(lastAST, currentAST);
+
+    // 5. Classify changes
+    return this.classifyChanges(diff, articleNode);
+  }
+
+  classifyChanges(diff: ASTDiff, articleNode: ArticleNode): ArticleChanges {
+    const changes: ArticleChanges = {
+      structural: [],  // New sections, removed sections
+      factual: [],     // Changed facts (command names, parameters, etc.)
+      editorial: [],   // Wording, examples, explanations
+      metadata: []     // Frontmatter changes
+    };
+
+    for (const change of diff.changes) {
+      if (this.isStructuralChange(change)) {
+        changes.structural.push(change);
+      } else if (this.isFactualChange(change)) {
+        changes.factual.push(change);
+      } else {
+        changes.editorial.push(change);
+      }
+    }
+
+    return changes;
+  }
+
+  isFactualChange(change: Change): boolean {
+    // Factual changes affect the knowledge graph
+    // Examples: command names, parameter types, exit codes
+    return (
+      change.affects('command.name') ||
+      change.affects('parameter.type') ||
+      change.affects('example.command') ||
+      change.affects('error.exit_code')
+    );
+  }
+}
+```
+
+**Graph Changes (Programmatic Updates):**
+
+```typescript
+class GraphChangeDetector {
+  async detectChanges(): Promise<GraphChanges> {
+    // Use graph's built-in change tracking
+    const query = `
+      MATCH (n)
+      WHERE n.updated_at > $lastCheck
+      RETURN n, labels(n) as type
+    `;
+
+    const changedNodes = await this.knowledgeGraph.query(query, {
+      lastCheck: this.lastCheckpoint
+    });
+
+    return {
+      nodes: changedNodes,
+      affectedArticles: await this.findAffectedArticles(changedNodes)
+    };
+  }
+
+  async findAffectedArticles(changedNodes: Node[]): Promise<ArticleNode[]> {
+    const nodeIds = changedNodes.map(n => n.id);
+
+    const query = `
+      MATCH (a:Article)-[:DOCUMENTS*1..3]->(n)
+      WHERE n.id IN $nodeIds
+      RETURN DISTINCT a
+    `;
+
+    return this.knowledgeGraph.query(query, { nodeIds });
+  }
+}
+```
+
+### Sync Directions
+
+**Direction 1: Article → Graph (Human edits articles)**
+
+```typescript
+class ArticleToGraphSync {
+  async syncArticleChanges(changes: ArticleChanges): Promise<SyncResult> {
+    const updates: GraphUpdate[] = [];
+
+    // 1. Apply structural changes
+    for (const change of changes.structural) {
+      if (change.type === 'section_added') {
+        // Extract new content and create graph nodes
+        const newNodes = await this.extractNodesFromSection(change.section);
+        updates.push({ type: 'create', nodes: newNodes });
+      } else if (change.type === 'section_removed') {
+        // Mark nodes as deprecated or remove relationships
+        updates.push({ type: 'deprecate', nodes: change.affectedNodes });
+      }
+    }
+
+    // 2. Apply factual changes
+    for (const change of changes.factual) {
+      const node = await this.findNodeForChange(change);
+      updates.push({
+        type: 'update',
+        nodeId: node.id,
+        field: change.field,
+        oldValue: change.oldValue,
+        newValue: change.newValue
+      });
+    }
+
+    // 3. Editorial changes don't affect graph
+    // They're preserved as article-specific styling
+
+    // 4. Apply all updates to graph
+    return this.applyUpdates(updates);
+  }
+
+  async extractNodesFromSection(section: MarkdownSection): Promise<Node[]> {
+    // Use LLM to extract structured data from markdown
+    const prompt = `
+      Extract structured knowledge from this documentation section:
+
+      ${section.content}
+
+      Identify:
+      - Commands (name, description, parameters)
+      - Examples (command, expected output)
+      - Concepts (name, description, relationships)
+      - Errors (message, exit code, suggestions)
+
+      Return as JSON matching our graph schema.
+    `;
+
+    const extracted = await this.llm.complete(prompt, { format: 'json' });
+    return this.convertToGraphNodes(extracted);
+  }
+}
+```
+
+**Direction 2: Graph → Articles (Programmatic updates to graph)**
+
+```typescript
+class GraphToArticleSync {
+  async syncGraphChanges(changes: GraphChanges): Promise<SyncResult> {
+    const affectedArticles = changes.affectedArticles;
+
+    for (const article of affectedArticles) {
+      // Check for conflicts (has article been edited since last generation?)
+      const hasHumanEdits = await this.hasHumanEdits(article);
+
+      if (hasHumanEdits) {
+        // Conflict! Needs resolution
+        await this.raiseConflict({
+          article: article.path,
+          graphChanges: changes.nodes,
+          humanEdits: await this.getHumanEdits(article)
+        });
+      } else {
+        // Safe to regenerate
+        await this.regenerateArticle(article);
+      }
+    }
+
+    return { success: true, conflicts: this.conflicts };
+  }
+
+  async hasHumanEdits(article: ArticleNode): Promise<boolean> {
+    // Compare file modification time with last_generated timestamp
+    const fileStats = await stat(article.path);
+    return fileStats.mtime > article.last_generated;
+  }
+}
+```
+
+---
+
+## Conflict Resolution
+
+### Conflict Scenarios
+
+**Scenario 1: Simultaneous Edits**
+```
+Graph: Command parameter "status" changed from optional to required
+Article: Human added example showing command without "status" parameter
+
+Conflict: Example no longer valid
+```
+
+**Scenario 2: Divergent Facts**
+```
+Graph: Command exit code is 1 on error
+Article: Human documented exit code as 0 (incorrect)
+
+Conflict: Which is correct?
+```
+
+**Scenario 3: Structure vs Content**
+```
+Graph: Command deprecated, marked for removal
+Article: Human added extensive tutorial about the command
+
+Conflict: Keep tutorial or remove?
+```
+
+### Resolution Strategies
+
+**Strategy 1: Graph Wins (Default for Facts)**
+
+```typescript
+class GraphWinsResolver implements ConflictResolver {
+  resolve(conflict: Conflict): Resolution {
+    // For factual conflicts, graph is source of truth
+    if (conflict.type === 'factual') {
+      return {
+        action: 'use_graph',
+        reasoning: 'Knowledge graph is authoritative for facts',
+        preserveHumanEdit: false
+      };
+    }
+
+    return { action: 'escalate' };
+  }
+}
+```
+
+**Strategy 2: Human Wins (For Editorial)**
+
+```typescript
+class HumanWinsResolver implements ConflictResolver {
+  resolve(conflict: Conflict): Resolution {
+    // For editorial changes, preserve human intent
+    if (conflict.type === 'editorial') {
+      return {
+        action: 'use_article',
+        reasoning: 'Human editorial improvements should be preserved',
+        syncBackToGraph: false
+      };
+    }
+
+    return { action: 'escalate' };
+  }
+}
+```
+
+**Strategy 3: Merge (Best Effort)**
+
+```typescript
+class MergeResolver implements ConflictResolver {
+  async resolve(conflict: Conflict): Promise<Resolution> {
+    // Use AI to attempt intelligent merge
+    const prompt = `
+      There is a conflict between the knowledge graph and article:
+
+      Graph says: ${conflict.graphVersion}
+      Article says: ${conflict.articleVersion}
+
+      The conflict type is: ${conflict.type}
+
+      Can these be merged? If so, how?
+      If not, which should take precedence and why?
+    `;
+
+    const resolution = await this.llm.complete(prompt);
+    return this.parseResolution(resolution);
+  }
+}
+```
+
+**Strategy 4: Three-Way Merge (Most Robust)**
+
+```typescript
+class ThreeWayMergeResolver implements ConflictResolver {
+  resolve(conflict: Conflict): Resolution {
+    // Compare:
+    // 1. Last generated version (base)
+    // 2. Current graph version
+    // 3. Current article version
+
+    const base = conflict.lastGeneratedVersion;
+    const graph = conflict.graphVersion;
+    const article = conflict.articleVersion;
+
+    if (graph === base && article !== base) {
+      // Only article changed → use article
+      return { action: 'use_article', syncBackToGraph: true };
+    } else if (article === base && graph !== base) {
+      // Only graph changed → use graph
+      return { action: 'use_graph' };
+    } else {
+      // Both changed → conflict!
+      return {
+        action: 'manual_review',
+        versions: { base, graph, article },
+        suggestedResolution: this.suggestMerge(base, graph, article)
+      };
+    }
+  }
+}
+```
+
+### Conflict UI
+
+```typescript
+// Interactive conflict resolution interface
+class ConflictResolutionUI {
+  async presentConflict(conflict: Conflict): Promise<Resolution> {
+    console.log(`
+┌─────────────────────────────────────────────────────────┐
+│ 🚨 CONFLICT DETECTED                                     │
+├─────────────────────────────────────────────────────────┤
+│ File: ${conflict.article.path}                          │
+│ Type: ${conflict.type}                                  │
+│                                                         │
+│ ❓ What should we do?                                   │
+└─────────────────────────────────────────────────────────┘
+
+📊 Graph Version (Programmatic):
+${highlight(conflict.graphVersion)}
+
+✏️  Article Version (Human Edit):
+${highlight(conflict.articleVersion)}
+
+🔀 Options:
+  1) Use graph version (discard human edit)
+  2) Use article version (update graph to match)
+  3) Merge both (AI-assisted)
+  4) Edit manually
+  5) Skip for now
+
+Choice:
+    `);
+
+    const choice = await this.prompt();
+    return this.handleChoice(choice, conflict);
+  }
+}
+```
+
+---
+
+## Implementation Design
+
+### Database Schema (Neo4j Example)
+
+```cypher
+// Create constraints
+CREATE CONSTRAINT command_id IF NOT EXISTS
+FOR (c:Command) REQUIRE c.id IS UNIQUE;
+
+CREATE CONSTRAINT article_path IF NOT EXISTS
+FOR (a:Article) REQUIRE a.path IS UNIQUE;
+
+// Create indexes for common queries
+CREATE INDEX command_name IF NOT EXISTS
+FOR (c:Command) ON (c.name);
+
+CREATE INDEX article_category IF NOT EXISTS
+FOR (a:Article) ON (a.category);
+
+// Full-text search
+CREATE FULLTEXT INDEX article_content IF NOT EXISTS
+FOR (a:Article) ON EACH [a.title, a.description];
+```
+
+### Core System Components
+
+**Component 1: Knowledge Graph Manager**
+
+```typescript
+class KnowledgeGraphManager {
+  constructor(private neo4j: Neo4jDriver) {}
+
+  // CRUD operations
+  async createNode(type: string, properties: any): Promise<Node> {
+    const query = `
+      CREATE (n:${type} $properties)
+      SET n.id = randomUUID(),
+          n.created_at = datetime(),
+          n.updated_at = datetime()
+      RETURN n
+    `;
+    return this.neo4j.run(query, { properties });
+  }
+
+  async updateNode(id: string, updates: any): Promise<Node> {
+    const query = `
+      MATCH (n {id: $id})
+      SET n += $updates,
+          n.updated_at = datetime()
+      RETURN n
+    `;
+    return this.neo4j.run(query, { id, updates });
+  }
+
+  async createRelationship(
+    fromId: string,
+    toId: string,
+    type: string,
+    properties?: any
+  ): Promise<Relationship> {
+    const query = `
+      MATCH (from {id: $fromId}), (to {id: $toId})
+      CREATE (from)-[r:${type} $properties]->(to)
+      RETURN r
+    `;
+    return this.neo4j.run(query, { fromId, toId, properties });
+  }
+
+  // Versioning
+  async createSnapshot(label: string): Promise<Snapshot> {
+    const query = `
+      MATCH (n)
+      WITH collect(n) as nodes
+      CREATE (s:Snapshot {
+        id: randomUUID(),
+        label: $label,
+        created_at: datetime(),
+        node_count: size(nodes)
+      })
+      RETURN s
+    `;
+    return this.neo4j.run(query, { label });
+  }
+
+  async restoreSnapshot(snapshotId: string): Promise<void> {
+    // Restore graph to previous snapshot state
+    // Implementation depends on versioning strategy
+  }
+}
+```
+
+**Component 2: Sync Coordinator**
+
+```typescript
+class SyncCoordinator {
+  constructor(
+    private graphManager: KnowledgeGraphManager,
+    private articleGenerator: ArticleGenerator,
+    private changeDetector: ChangeDetector,
+    private conflictResolver: ConflictResolver
+  ) {}
+
+  async syncAll(direction: 'graph_to_articles' | 'articles_to_graph' | 'bidirectional') {
+    if (direction === 'graph_to_articles' || direction === 'bidirectional') {
+      await this.syncGraphToArticles();
+    }
+
+    if (direction === 'articles_to_graph' || direction === 'bidirectional') {
+      await this.syncArticlesToGraph();
+    }
+  }
+
+  async syncGraphToArticles(): Promise<SyncResult> {
+    // 1. Detect graph changes
+    const graphChanges = await this.changeDetector.detectGraphChanges();
+
+    if (graphChanges.length === 0) {
+      return { status: 'up_to_date' };
+    }
+
+    // 2. Find affected articles
+    const affectedArticles = await this.findAffectedArticles(graphChanges);
+
+    // 3. For each article, check for conflicts
+    const results = [];
+    for (const article of affectedArticles) {
+      const hasConflict = await this.checkForConflicts(article, graphChanges);
+
+      if (hasConflict) {
+        const resolution = await this.conflictResolver.resolve(hasConflict);
+        results.push(await this.applyResolution(resolution));
+      } else {
+        // No conflict, regenerate
+        results.push(await this.articleGenerator.generateArticle(article.id));
+      }
+    }
+
+    return { status: 'synced', results };
+  }
+
+  async syncArticlesToGraph(): Promise<SyncResult> {
+    // 1. Detect article changes
+    const articleChanges = await this.changeDetector.detectArticleChanges();
+
+    if (articleChanges.length === 0) {
+      return { status: 'up_to_date' };
+    }
+
+    // 2. Extract graph updates from changes
+    const graphUpdates = [];
+    for (const change of articleChanges) {
+      if (change.type === 'factual') {
+        const update = await this.extractGraphUpdate(change);
+        graphUpdates.push(update);
+      }
+    }
+
+    // 3. Apply updates to graph
+    for (const update of graphUpdates) {
+      await this.graphManager.applyUpdate(update);
+    }
+
+    return { status: 'synced', updates: graphUpdates.length };
+  }
+}
+```
+
+**Component 3: Article Generator (Enhanced)**
+
+```typescript
+class SmartArticleGenerator extends ArticleGenerator {
+  // Preserve human editorial changes during regeneration
+  async generateArticlePreservingEdits(
+    articleId: string,
+    humanEdits: EditorialChange[]
+  ): Promise<GeneratedArticle> {
+    // 1. Generate fresh article from graph
+    const generatedArticle = await super.generateArticle(articleId);
+
+    // 2. Parse both versions
+    const generatedAST = parseMarkdown(generatedArticle.content);
+    const currentContent = await readFile(articleId);
+    const currentAST = parseMarkdown(currentContent);
+
+    // 3. Identify editorial sections to preserve
+    const preserveSections = this.identifyEditorialSections(currentAST, humanEdits);
+
+    // 4. Merge: use generated for facts, current for editorial
+    const mergedAST = this.mergeASTs(generatedAST, currentAST, preserveSections);
+
+    // 5. Render back to markdown
+    return {
+      ...generatedArticle,
+      content: renderMarkdown(mergedAST)
+    };
+  }
+
+  identifyEditorialSections(ast: MarkdownAST, edits: EditorialChange[]): Section[] {
+    // Find sections that contain purely editorial content
+    // (no factual data from graph)
+    return ast.sections.filter(section =>
+      this.isPurelyEditorial(section) &&
+      this.wasEditedByHuman(section, edits)
+    );
+  }
+
+  mergeASTs(
+    generated: MarkdownAST,
+    current: MarkdownAST,
+    preserveSections: Section[]
+  ): MarkdownAST {
+    const merged = { ...generated };
+
+    for (const section of preserveSections) {
+      // Replace generated section with human version
+      const sectionIndex = merged.sections.findIndex(s =>
+        s.heading === section.heading
+      );
+
+      if (sectionIndex >= 0) {
+        merged.sections[sectionIndex] = section;
+      }
+    }
+
+    return merged;
+  }
+}
+```
+
+---
+
+## User Workflows
+
+### Workflow 1: Technical Writer Updates Documentation
+
+**Before Kenogami (Traditional):**
+```
+1. Writer edits campaigns.md
+2. Writer edits getting-started.md
+3. Writer edits command-reference.md
+4. (Oops, forgot to update examples in tutorial.md)
+5. (Oops, parameter description inconsistent across files)
+```
+
+**With Kenogami (Graph-First):**
+```
+1. Writer opens Kenogami UI
+2. Writer finds "campaigns create" command node
+3. Writer edits parameter description in ONE place
+4. Clicks "Regenerate affected articles" (4 articles updated automatically)
+5. Reviews changes, approves
+6. All articles now consistent ✅
+```
+
+### Workflow 2: Developer Adds New Command
+
+**Before:**
+```
+1. Developer implements `campaigns schedule` command
+2. Developer documents it in campaigns.ts JSDoc
+3. (Forgets to update user manual)
+4. (User reads outdated docs, reports "missing feature")
+```
+
+**With Kenogami:**
+```
+1. Developer implements `campaigns schedule` command
+2. Developer adds to knowledge graph (via script or UI):
+   - Command node
+   - Parameter nodes
+   - Example nodes
+   - Related command links
+3. Run: `kenogami sync --direction graph-to-articles`
+4. All relevant articles auto-updated ✅
+   - Command reference updated
+   - Tutorial examples added
+   - Related commands section updated
+```
+
+### Workflow 3: Resolving Conflicts
+
+**Scenario:**
+```
+Developer: Marks command as deprecated in graph
+Writer: Just wrote extensive tutorial about that command
+```
+
+**Resolution:**
+```
+1. Kenogami detects conflict during sync
+2. Shows side-by-side comparison:
+
+   Graph: status = "deprecated_in_v2.0"
+   Article: Contains 500-word tutorial (recently edited)
+
+3. Presents options:
+   a) Keep tutorial, add deprecation notice
+   b) Remove tutorial
+   c) Move tutorial to "Legacy Commands" section
+
+4. Writer chooses (a)
+5. Kenogami:
+   - Preserves tutorial content
+   - Adds deprecation notice at top
+   - Updates all links to point to replacement command
+```
+
+---
+
+## Integration with AI Testing
+
+### Bidirectional Benefit for Testing
+
+**Testing Flow with Kenogami:**
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ 1. Knowledge Graph (Source of Truth)                     │
+│    - Commands, parameters, expected outputs              │
+└────────────────┬─────────────────────────────────────────┘
+                 │
+         ┌───────┴────────┐
+         │                │
+         ▼                ▼
+┌──────────────┐  ┌──────────────┐
+│  Articles    │  │ Test Cases   │
+│ (Generated)  │  │ (Generated)  │
+└──────┬───────┘  └──────┬───────┘
+       │                 │
+       │                 │
+       └────────┬────────┘
+                ▼
+       ┌─────────────────┐
+       │  AI Testing      │
+       │  Validation      │
+       └────────┬─────────┘
+                │
+                ▼
+       ┌─────────────────┐
+       │ Test Results     │
+       │ (Pass/Fail)      │
+       └────────┬─────────┘
+                │
+                │ If fail: Update graph OR article
+                ▼
+       ┌─────────────────┐
+       │ Feedback Loop    │
+       │ to Graph         │
+       └──────────────────┘
+```
+
+**Enhanced Test Generation:**
+
+```typescript
+class KenogamiTestGenerator extends TestCaseGenerator {
+  constructor(private knowledgeGraph: KnowledgeGraph) {
+    super();
+  }
+
+  async generateTestsFromGraph(): Promise<TestCase[]> {
+    // Query graph for all commands
+    const commands = await this.knowledgeGraph.query(`
+      MATCH (c:Command)
+      OPTIONAL MATCH (c)-[:HAS_PARAMETER]->(p:Parameter)
+      OPTIONAL MATCH (c)-[:HAS_EXAMPLE]->(e:Example)
+      RETURN c, collect(p) as parameters, collect(e) as examples
+    `);
+
+    // Generate test cases directly from graph
+    return commands.map(cmd => ({
+      id: `TEST-${cmd.c.id}`,
+      command: this.buildCommandString(cmd.c, cmd.parameters),
+      expectedBehavior: {
+        exitCode: 0,
+        output: cmd.examples[0]?.expected_output,
+        schema: this.generateSchemaFromParameters(cmd.parameters)
+      }
+    }));
+  }
+
+  async feedbackFailureToGraph(testResult: TestResult): Promise<void> {
+    if (!testResult.passed) {
+      // Analyze failure
+      const analysis = await this.analyzeFailure(testResult);
+
+      if (analysis.type === 'documentation_issue') {
+        // Update graph with correct information
+        await this.knowledgeGraph.updateNode(analysis.nodeId, {
+          [analysis.field]: analysis.correctValue,
+          updated_by: 'ai_testing',
+          updated_reason: analysis.reason
+        });
+
+        // Trigger article regeneration
+        await this.syncCoordinator.syncGraphToArticles();
+      }
+    }
+  }
+}
+```
+
+**Test Results Feed Back to Graph:**
+
+```typescript
+// When tests discover undocumented behavior
+class TestResultAnalyzer {
+  async analyzeAndUpdateGraph(results: TestResult[]): Promise<GraphUpdate[]> {
+    const updates = [];
+
+    for (const result of results) {
+      if (result.passed && result.confidence < 0.8) {
+        // Test passed but with low confidence - might be undocumented behavior
+        const analysis = await this.llm.analyze(`
+          Test passed but documentation was unclear:
+
+          Command: ${result.testCase.command}
+          Expected: ${result.testCase.expectedBehavior}
+          Actual: ${result.actualOutput}
+
+          Should we update the knowledge graph with this information?
+        `);
+
+        if (analysis.should_update) {
+          updates.push({
+            nodeId: result.testCase.commandId,
+            field: analysis.field,
+            newValue: analysis.value,
+            source: 'ai_testing_discovery'
+          });
+        }
+      }
+
+      if (!result.passed && result.actualBehaviorIsCorrect) {
+        // Test failed because documentation is wrong
+        updates.push({
+          nodeId: result.testCase.commandId,
+          field: result.mismatchField,
+          oldValue: result.expected,
+          newValue: result.actual,
+          source: 'ai_testing_correction'
+        });
+      }
+    }
+
+    // Apply updates to graph
+    for (const update of updates) {
+      await this.knowledgeGraph.applyUpdate(update);
+    }
+
+    return updates;
+  }
+}
+```
+
+---
+
+## Summary: Impact on Flow
+
+### Before Kenogami (Traditional)
+
+```
+Articles → Extract → Knowledge Graph → Generate Tests → Validate
+
+Problems:
+- Articles can be inconsistent
+- Changes require manual updates in multiple places
+- Graph is read-only, can't improve from testing
+- Documentation drift over time
+```
+
+### With Kenogami (Bidirectional)
+
+```
+                    ┌─ Generate → Articles
+                    │
+Knowledge Graph ────┼─ Generate → Test Cases
+     ▲              │
+     │              └─ Generate → API Specs
+     │
+     └─ Updates from: Test Results, Human Edits, Code Analysis
+
+Benefits:
+✅ Single source of truth (the graph)
+✅ Automatic consistency
+✅ Test results improve documentation
+✅ Multi-format output (articles, tests, specs) always in sync
+✅ Changes propagate everywhere automatically
+```
+
+### Key Architectural Shifts
+
+| Aspect | Traditional | Kenogami |
+|--------|-------------|----------|
+| **Source of Truth** | Articles | Knowledge Graph |
+| **Article Creation** | Manual writing | Generated from graph |
+| **Updates** | Edit articles | Edit graph → regenerate |
+| **Consistency** | Manual effort | Automatic |
+| **Test Generation** | From articles | From graph (more reliable) |
+| **Test Feedback** | Manual fix docs | Auto-update graph |
+| **Multi-Format** | Duplicate content | Single source, multiple outputs |
+| **Version Control** | File-based | Graph snapshots + files |
+
+### Migration Path
+
+```
+Phase 1: Build graph from existing articles (one-time)
+Phase 2: Validate graph completeness
+Phase 3: Generate articles from graph (verify output)
+Phase 4: Enable bidirectional sync (with conflicts)
+Phase 5: Full graph-first workflow
+```
+
+---
+
+## Conclusion
+
+**Kenogami transforms documentation from static files into a living knowledge system** where:
+
+1. **Knowledge Graph is authoritative** - Facts live in one place
+2. **Articles are generated views** - Consistent, up-to-date, multi-format
+3. **Bidirectional sync** - Accept edits from both humans and automation
+4. **Testing drives documentation** - Failed tests improve the graph
+5. **Scale effortlessly** - Add CLI, Web, Mobile docs without duplication
+
+This architecture is **ideal for AI testing** because the knowledge graph provides a **single, queryable, version-controlled source of truth** that both generates documentation AND test cases, creating a self-improving system.