tycono 0.3.45-beta.2 → 0.3.45-beta.3

package/packages/server/templates/CLAUDE.md.tmpl

@@ -0,0 +1,152 @@
+# Your Knowledge Base
+
+> Powered by [Tycono](https://tycono.ai)
+
+---
+
+## AKB Core Concept
+
+> **AKB** = File-based knowledge system where AI finds via **Search (Grep/Glob)** and navigates via **Contextual Links**
+
+| Layer | Role | AI Usage |
+|-------|------|----------|
+| **Root** (CLAUDE.md) | Minimal routing | Auto-injected as system prompt |
+| **Hub** ({folder}.md) | Human TOC + guides | **Check before starting work** |
+| **Node** (*.md) | Actual information | Direct search via Grep/Glob |
+
+---
+
+## AI Working Rules (CRITICAL)
+
+### Hub-First Principle
+
+> ⛔ **Read Hub document BEFORE implementing/testing**
+
+Based on AKB observations, AI tends to skip Hubs and search directly.
+But **Hubs contain existing tools/scripts/guides** - missing them causes redundant work.
+
+Every folder has a Hub file (`{folder-name}.md`) as its entry point.
+Read the Hub's existing tools/scripts/guides before starting work.
+
+### Required Check Situations
+
+| Situation | Read First | What to Find |
+|-----------|------------|--------------|
+| Debugging/Testing | Hub → guides/ | Existing debug tools |
+| API Calls | Hub → related Node | Documented methods |
+| New Feature | Hub | Similar existing features |
+| Strategy/Design | Hub + detail docs | Design philosophy, past decisions |
+
+### Correct Patterns
+
+```
+✅ Debugging
+   → {domain}.md (Hub) → guides/debugging.md
+   → Use existing debug scripts
+
+✅ Testing
+   → {domain}.md (Hub) → test utilities
+
+✅ API Integration
+   → api.md (Hub) → existing client libraries
+```
+
+### Anti-Patterns
+
+```
+❌ Skip Hub → curl API directly
+❌ Skip Hub → Write scripts from scratch
+❌ Skip Hub → Start with assumptions
+```
+
+---
+
+## Exploration Depth Principle
+
+> ⛔ **For strategy/idea questions, Hub alone is NOT enough. Explore detail docs.**
+
+AI tends to read a few Hubs and judge "sufficient".
+But **strategic questions need specific context** - shallow exploration leads to superficial answers.
+
+### Exploration Depth by Question Type
+
+| Question Type | Minimum | Additional |
+|---------------|---------|------------|
+| Implementation | Hub | Related Nodes |
+| Debugging/Testing | Hub → guides/ | Existing tools |
+| **Strategy/Ideas** | Hub | **Design philosophy, core problems, phase docs** |
+| **Connecting A and B** | **Both Hubs** | **Both core docs (design, business, phases)** |
+
+### When Deep Exploration is Needed
+
+```
+✅ "How to connect System A and System B?"
+   → system-a.md + system-b.md (both Hubs)
+   → architecture.md (system design)
+   → security-model.md (design philosophy)
+   → business-requirements.md (business context)
+
+✅ "Ideas for improving performance?"
+   → {domain}.md (Hub)
+   → performance-analysis.md (problem details, current approach)
+
+✅ "Apply this architecture to another domain?"
+   → architecture.md (Hub)
+   → design-philosophy.md (domain-independent principles)
+```
+
+### Risks of Shallow Exploration
+
+```
+❌ Read only a few Hubs → "sufficient" judgment → superficial ideas
+❌ List only technical features → No connection to actual problems
+❌ Deep dive one side only → Forced fitting (bad integration)
+```
+
+> **Domain ≠ Core Problem**
+> Knowing "what the service is" but not "what's the core problem" → Technology pushing happens.
+> AKB Hubs specify core problems, enabling "problem-centered" connections.
+
+---
+
+## Knowledge Gate
+
+> **Before creating a new document, search existing docs first.**
+
+```
+1. Summarize the insight + 3-5 keywords
+2. Search existing docs with those keywords (grep 3+ terms)
+3. Decide:
+   - Overlap 70%+ -> Add to existing document
+   - Overlap 30-70% -> New doc + cross-link to existing
+   - Overlap <30% -> New document (register in Hub)
+   - Temporary info -> Journal only (no new doc)
+4. Cross-link to related docs
+5. Register in the relevant Hub
+```
+
+---
+
+## Document Hygiene
+
+| Rule | Description |
+|------|-------------|
+| No orphan docs | Every document must be reachable from a Hub |
+| Hub pattern | Each folder's entry point is `{folder}.md` |
+| Prefer existing | Adding 1 doc = maintenance cost. Strengthen existing > create new |
+| Cross-link | New docs must reference at least 1 related doc |
+| Source attribution | External research must cite source and date |
+
+---
+
+## Writing Rules (4 Principles)
+
+1. **TL;DR Required**: Include searchable keywords (bold)
+2. **Contextual Links**: Place links in body text with context
+3. **Keyword-Optimized Filenames**: `wallet-security.md` not `security.md`
+4. **Atomicity**: One topic per document, under 200 lines
+
+---
+
+<!-- tycono:managed v{{VERSION}} — This file is managed by Tycono. Do not edit manually. -->
+<!-- Company-specific rules go in custom-rules.md (knowledge/ root) -->

package/packages/server/templates/agentic-knowledge-base.md

@@ -0,0 +1,355 @@
+---
+title: Agentic Knowledge Base (AKB)
+akb_type: node
+status: active
+tags:
+  - type/how-to
+  - domain/akb
+---
+
+# Agentic Knowledge Base (AKB)
+
+**An autonomous knowledge protocol designed for AI agents**
+
+> This is the **Canonical Reference** for AKB.
+
+---
+
+## TL;DR
+
+- **Definition**: A file-based knowledge system where AI uses **search (Grep/Glob)** to find and **contextual links** to navigate
+- **Essence**: File-based Lightweight Ontology (Tag = Type, inline links = Edges)
+- **Philosophy**: Optimize documents so AI can find them — don't force AI to follow a rigid protocol
+- **Structure**: Root (CLAUDE.md) → Hub ({folder}.md) → Node (*.md)
+- **Core rules**: 5 writing principles (TL;DR, contextual links, keyword-optimized filenames, atomicity, semantic vs implementation separation)
+
+---
+
+## Definition
+
+> "Code is logic machines execute. AKB is context agents think with."
+
+AKB is a **file-based connected knowledge system** designed so AI agents can **search**, **learn**, and **retrieve** context without infrastructure (no Vector DB required).
+
+### Core Philosophy
+
+> "Don't try to inject everything into AI at once.
+> Instead, give it **documents that are easy to find**."
+
+---
+
+## Essence: File-Based Ontology
+
+> "Inject the spirit of Ontology into Markdown"
+
+```
+┌─────────────────────────────────────────────────────┐
+│           AKB = Lightweight Knowledge Graph          │
+├─────────────────────────────────────────────────────┤
+│                                                     │
+│   Ontology/KG                AKB                    │
+│   ───────────                ───                    │
+│   Entity (Node)       →      .md file               │
+│   rdf:type            →      tags: [type/]          │
+│   domain              →      tags: [domain/]        │
+│   rdfs:comment        →      TL;DR section          │
+│   Edge/Relationship   →      Inline contextual link │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Architecture
+
+AKB follows a 3-layer hierarchy: **[Root] → [Hub] → [Node]**.
+
+```
+project/
+├── CLAUDE.md                      # [Root] Minimal routing (key file paths)
+│
+└── knowledge/
+    │
+    ├── domain/                    # [Hub] TOC for humans
+    │   ├── domain.md              #   └─ Hub entry point
+    │   └── entity-id-system.md    # [Node] Concrete knowledge
+    │
+    ├── investigation/
+    │   ├── investigation.md       # [Hub]
+    │   ├── autotrace/
+    │   │   ├── autotrace.md       # [Sub-Hub]
+    │   │   ├── fifo-strategy.md   # [Node] ← AI finds via search
+    │   │   └── execution-flow.md  # [Node]
+```
+
+### Layer Roles
+
+| Layer | Role | Description |
+|-------|------|-------------|
+| **Root** (CLAUDE.md) | Minimal routing | Auto-injected as system prompt, provides key file paths |
+| **Hub** ({folder}.md) | TOC for humans | Folder overview; AI reads selectively |
+| **Node** (*.md) | Actual information | What AI searches for via Grep/Glob |
+
+---
+
+## Schema Specification
+
+### Frontmatter
+
+```yaml
+---
+title: "Document title"
+akb_type: hub|node
+status: active|draft|deprecated
+tags:
+  - "type/..."      # Document type
+  - "domain/..."    # Domain classification
+---
+```
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `title` | string | Document identification |
+| `akb_type` | enum | Distinguish hub/node |
+| `status` | enum | Document lifecycle |
+| `tags` | array | Domain classification (aids Grep search) |
+
+### Tags (Classification)
+
+| Namespace | Purpose | Examples |
+|-----------|---------|----------|
+| `type/` | Document type | `type/how-to`, `type/reference`, `type/api-guide` |
+| `domain/` | Domain classification | `domain/investigation`, `domain/blockchain` |
+
+---
+
+## Writing Principles (5 Rules)
+
+### Rule 1: TL;DR Required + Keyword Optimization
+
+Include **key search terms naturally** so AI can find them via Grep.
+
+```markdown
+## TL;DR
+
+- **AutoTrace** implements **FIFO tracking** strategy
+- **DEX/Swap** transaction **routing** pattern handling
+- **Bridge** cross-chain tracking logic
+```
+
+**Guidelines:**
+- 3-5 bullet points
+- **Bold key terms** (Grep search targets)
+- Keep each point to one line
+
+### Rule 2: Contextual Links (Inline)
+
+Place links **within the flow of text**, not in isolated lists.
+
+**Example 1: Natural inline placement**
+```markdown
+The core of Lambda Admin is the **[4-Layer classification system](./4-layer-architecture.md)**.
+
+The ontology store will migrate from ES to [Virtuoso/ClickHouse](./hybrid-federation.md).
+```
+
+**Example 2: Next steps section**
+```markdown
+## Next Steps
+
+- For DEX transaction handling → [dex-handling.md](./dex-handling.md)
+- For Bridge tracking → [bridge-patterns.md](./bridge-patterns.md)
+```
+
+**Why it works:** Context helps AI understand *why* it should follow the link.
+
+**Less effective pattern:**
+```markdown
+## Related Documentation  ← No context, just a list
+- [4-layer-architecture.md](./4-layer-architecture.md)
+- [hybrid-federation.md](./hybrid-federation.md)
+```
+→ Without context, AI can't judge *why* it should follow these links
+
+### Rule 3: Keyword-Optimized Filenames
+
+Make files easy to find via Grep/Glob with **descriptive filenames**.
+
+```
+❌ Vague
+notes.md
+strategy.md
+
+✅ Clear
+nexy-debugging.md
+autotrace-fifo-strategy.md
+bitcoin-utxo-handling.md
+```
+
+### Rule 4: Atomicity
+
+- One document = one topic
+- Keep under 200 lines (AI token efficiency)
+- If too long, split and connect via Hub
+
+### Rule 5: Semantic vs Implementation Separation
+
+> **Implementation (DDL, specs) → code repo** | **Semantic (meaning, relationships, why) → AKB**
+
+AKB holds knowledge for AI to **understand context**. Implementation details belong in the code repo.
+
+| Belongs in AKB | Belongs in Code Repo |
+|----------------|---------------------|
+| "Why we designed it this way" | DDL / migration files |
+| Relationship diagrams (Mermaid) | OpenAPI specs |
+| Design trade-offs | Config files (YAML/JSON) |
+
+**Reasons:**
+- **Sync issues**: Code changes require AKB updates → drift happens
+- **Single Source of Truth**: Code is the source of truth
+- **AKB essence**: Context for AI understanding ≠ implementation details
+
+**Recommended pattern:**
+```markdown
+> **DDL details**: See `{repo-name}` repo
+
+[Mermaid ERD showing relationships only]
+
+**Key design principles:**
+- Why we chose this design
+- What trade-offs exist
+```
+
+---
+
+## Document Structure Template
+
+```markdown
+# Title
+
+## TL;DR
+
+- **Keyword1**: Description
+- **Keyword2**: Description
+- **Keyword3**: Description
+
+---
+
+## Body
+
+### Section 1
+
+Content...
+See `path/file.md` for reference. (explicit path)
+
+### Section 2
+
+Content...
+
+---
+
+## Next Steps
+
+- If [situation A] → [fileA.md](./fileA.md)
+- If [situation B] → [fileB.md](./fileB.md)
+- If [situation C] → [fileC.md](../folder/fileC.md)
+```
+
+---
+
+## Hub Role
+
+```
+Hub = TOC for humans
+    + keyword collection that aids Grep searches
+```
+
+**Hub responsibilities:**
+1. Help humans understand folder contents
+2. Contain enough keywords to appear in Grep results
+3. AI reads selectively when it needs structural overview
+
+---
+
+## CLAUDE.md Routing Strategy
+
+CLAUDE.md is included in the system prompt, so it has **size constraints**.
+
+### Routing Principles
+
+```markdown
+# CLAUDE.md
+
+## Task Routing
+
+| Task | Entry Point |
+|------|-------------|
+| AutoTrace overview | `investigation/autotrace/autotrace.md` (Hub) |
+| FIFO tracking strategy | `investigation/autotrace/fifo-strategy.md` |
+| DEX handling | `investigation/autotrace/dex-handling.md` |
+```
+
+**Principles:**
+- Frequently used core files → direct path
+- Everything else → Hub reference
+
+---
+
+## vs Other Approaches
+
+| Comparison | AKB | RAG | System Prompt |
+|------------|-----|-----|---------------|
+| Infrastructure | None | Vector DB | None |
+| Token efficiency | Load only what's needed | Chunk-based | Load everything |
+| AI navigation | Grep + contextual links | Similarity search | None |
+| Maintenance | Edit files | Re-index | Edit prompt |
+
+---
+
+## Summary
+
+> **AKB** is a file-based knowledge system designed so AI can autonomously navigate knowledge.
+
+**Key points:**
+- Minimal frontmatter (4 fields only)
+- Connect via inline contextual links
+- Hubs are TOCs for humans
+- Optimize filenames and TL;DR for keyword search
+
+> "Rather than changing AI behavior, optimize documents so AI can find them."
+
+---
+
+## Next Steps
+
+- Tag system details → [tag-system.md](./tag-system.md)
+- Naming conventions → [naming-convention.md](./naming-convention.md)
+
+---
+
+## Design Background
+
+AKB was designed by analyzing actual AI agent behavior patterns.
+
+**Observed AI behavior:**
+- Skips Hubs, searches Nodes directly via Grep/Glob
+- Does not parse frontmatter metadata (triggers, related, etc.)
+- Follows links that appear inline with context
+
+**Design principle:**
+> "Don't try to change AI behavior — optimize documents so AI can find them naturally."
+
+### AKB Does Not Force Navigation on AI
+
+**AKB's responsibility lies with the document designer.**
+
+| Misconception | Correct Understanding |
+|---------------|----------------------|
+| "AI must consciously navigate using AKB" | AKB does not prescribe how AI navigates |
+| "AI must meta-recognize Hub intersections" | AI naturally finds what it needs |
+| "Is AI following AKB principles?" | If the answer is good, AKB worked |
+
+**Key insight:**
+> If AI found the information it needed and produced a good answer, that's proof AKB is working.
+> AI doesn't need to be meta-aware of "Am I following AKB right now?"
+> That's the document designer's responsibility, not the AI's.

package/src/api/src/services/claude-md-manager.ts

@@ -1,94 +0,0 @@
-/**
- * claude-md-manager.ts — CLAUDE.md lifecycle management
- *
- * CLAUDE.md is 100% Tycono-managed. This module handles:
- * - Version tracking via .tycono/rules-version
- * - Auto-regeneration on version mismatch (server startup)
- * - Backup of pre-existing CLAUDE.md (first time only)
- * - Stub creation for knowledge/custom-rules.md
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const TEMPLATES_DIR = path.resolve(__dirname, '../../../../templates');
-
-/**
- * Read the current package version from package.json
- */
-function getPackageVersion(): string {
-  const pkgPath = path.resolve(__dirname, '../../../../package.json');
-  try {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-    return pkg.version || '0.0.0';
-  } catch {
-    return '0.0.0';
-  }
-}
-
-/**
- * Generate CLAUDE.md content from template with version marker
- */
-function generateClaudeMd(version: string): string {
-  const tmplPath = path.join(TEMPLATES_DIR, 'CLAUDE.md.tmpl');
-  const template = fs.readFileSync(tmplPath, 'utf-8');
-  return template.replaceAll('{{VERSION}}', version);
-}
-
-/**
- * Ensure CLAUDE.md is up-to-date with the current package version.
- *
- * Called on server startup. Compares .tycono/rules-version with package version.
- * If different, regenerates CLAUDE.md from template (safe because CLAUDE.md
- * contains 0% user data — all user customization is in knowledge/custom-rules.md).
- */
-export function ensureClaudeMd(companyRoot: string): void {
-  const tyconoDir = path.join(companyRoot, '.tycono');
-  const rulesVersionPath = path.join(tyconoDir, 'rules-version');
-  const claudeMdPath = path.join(companyRoot, 'knowledge', 'CLAUDE.md');
-  const knowledgeDir = path.join(companyRoot, 'knowledge');
-  const customRulesPath = path.join(knowledgeDir, 'custom-rules.md');
-  const backupPath = path.join(tyconoDir, 'CLAUDE.md.backup');
-
-  // Skip if not initialized (no .tycono/ directory)
-  if (!fs.existsSync(tyconoDir)) return;
-
-  const currentVersion = getPackageVersion();
-
-  // Read stored version
-  let storedVersion = '0.0.0';
-  if (fs.existsSync(rulesVersionPath)) {
-    storedVersion = fs.readFileSync(rulesVersionPath, 'utf-8').trim();
-  }
-
-  // Skip if already up-to-date
-  if (storedVersion === currentVersion) return;
-
-  // Backup existing CLAUDE.md (first time only — don't overwrite previous backup)
-  if (fs.existsSync(claudeMdPath) && !fs.existsSync(backupPath)) {
-    fs.copyFileSync(claudeMdPath, backupPath);
-    console.log(`[CLAUDE.md] Backed up existing CLAUDE.md to .tycono/CLAUDE.md.backup`);
-  }
-
-  // Regenerate CLAUDE.md from template
-  const content = generateClaudeMd(currentVersion);
-  fs.writeFileSync(claudeMdPath, content);
-
-  // Update rules-version
-  fs.writeFileSync(rulesVersionPath, currentVersion);
-
-  // Create custom-rules.md stub if not exists
-  if (!fs.existsSync(customRulesPath)) {
-    fs.writeFileSync(customRulesPath, `# Custom Rules
-
-> Company-specific rules, constraints, and processes.
-> This file is owned by you — Tycono will never overwrite it.
-
-<!-- Add your custom rules below -->
-`);
-  }
-
-  console.log(`[CLAUDE.md] System rules updated to v${currentVersion} (was v${storedVersion})`);
-}