wikijs_data/home.md

title	description	published	date	tags	editor	dateCreated
Jiki Documentation Strategy	home	true	2025-04-06T03:37:28.811Z		markdown	2025-04-04T07:01:55.964Z

🔍 Metadata (click to view)

title: "Janusian Documentation Strategy"
description: "A strategy for building human-readable, RAG-optimized documentation for AI agents at NeuroMentum."
classification: "internal"
document_type: "concept"
access_groups: "neuromentum"
project: "infra_docs"
category: "meta"
tags: ["documentation", "RAG", "ai_agent", "wiki", "postgres"]
hierarchy: ["meta"]
created: "2025-04-04"
last_reviewed: "2025-04-04"
agent_usage_hint: "Use this strategy to format all documentation for dual human-agent readability."
version: "v1"

🪶 Janusian Documentation Strategy

For AI Agent & PostgreSQL Infrastructure at NeuroMentum

---

🌟 Preamble: The Janusian Vision

Our documentation is more than technical scaffolding — it’s an interface between human insight and machine inference. Following Janusian design principles, this plan ensures:

• 🧠 Human-readability (wiki-style hierarchy, intuitive naming)
• 🤖 AI-compatibility (semantic metadata, chunked content, retriever-optimized)
• 🔄 Dual-perspective thinking: all docs are shaped for both intelligent co-developers and intelligent consumers (agents, LLMs, and future tools)
• 🔮 Future-proofing via metadata, version control, and traceable structure

---

📁 1. Folder Hierarchy: Wiki-Readable, Logically Scoped

Keep folder structure intuitive, max 3–4 levels deep:

docs/
├── postgres/
│   ├── schemas/
│   ├── monitoring/
│   └── admin_tasks/
├── personas/
│   ├── chatgpt/
│   ├── khebri/
│   ├── scarabone/
│   └── scarabtwo/
├── agent_architecture/
│   ├── kafka/
│   ├── llm_integration/
│   └── task_orchestration/
├── reference/
│   └── utf8_handling.md
└── manifest.md

📌 Each folder = a logical domain
📌 Each file = a self-contained, RAG-chunkable unit

---

🏷️ 2. Embedded Metadata per File

Every file begins with structured YAML frontmatter:

---
title: "Khebri Schema"
description: "PostgreSQL schema for thread tracking and status."
project: "chatBCI"
category: "schemas"
tags: ["postgres", "khebri", "thread", "active_status", "sql"]
hierarchy: ["postgres", "schemas"]
created: "2025-03-31"
last_reviewed: "2025-04-04"
visibility: ["human", "ai_agent", "scout_agent"]
agent_usage_hint: "Use when setting up or querying thread states"
version: "v1"
---

📎 Purpose:

• Helps RAG engines filter and rank results
• Enables traceability for future tooling
• Bridges intent between human and AI agents

---

📦 3. Chunking + RAG Readiness Guidelines

Each doc should:

• Be under 1000–1500 tokens per section
• Use semantic headings (e.g., ## Create Thread Table, ## Reset Identity Counter)
• Include examples + explanations (Why, When, How)
• Add "Janusian Intent" callouts:

> 🧠 Janusian Intent: This query resets identity counters to preserve clean state across simulation iterations and testing loops.

---

🧠 4. Central Metadata Registry: janus_index.json

Maintained at project root (docs/), this file tracks every document:

{
  "docs/postgres/schemas/khebri.sql": {
    "title": "Khebri Schema",
    "tags": ["postgres", "schema", "threads"],
    "hierarchy": ["postgres", "schemas"],
    "version": "v1",
    "agent_usage_hint": "Used during thread setup, task tracking",
    "visibility": ["ai_agent", "human"]
  }
}

💡 Bonus: Later you can auto-generate this via a crawler script.

---

🧬 5. Versioning + Change History

Use simple folder or file-based versioning:

docs/
└── personas/
    └── khebri/
        ├── v1.md
        └── v2.md

Or append version into frontmatter and add CHANGELOG.md per folder:

version: "v2"
changelog:
  - "2025-04-01: Added updated persona structure"
  - "2025-03-31: Initial draft"

---

⚙️ 6. RAG Integration Features (Future-Ready)

Later, these files can power:

• Chunk-based vector search
• Metadata + embedding fusion retrieval
• Agent-specific prompt context filters (via tags, hierarchy, agent_usage_hint)
• Access gating with visibility field

📦 Optional: Extend with graph or relations fields to define links:

graph:
  links_to: ["state_transitions.md", "thread_multistates.md"]
  agent_role: "architect"

---

🚀 7. Starter Scripts to Support This System

We can build:

• build_index.py: Scans folders, extracts frontmatter, outputs janus_index.json
• chunk_docs.py: Breaks large docs into overlapping chunks with hierarchy/context
• rag_query_preview.py: Preview which doc chunks would be retrieved for a given question

Let me know if you'd like these generated! 💻

---

🧭 8. Agent-Aware Style Guidelines

Style Area	Guideline
💬 Headings	Use ## or ### consistently for chunk boundaries
💡 Intent Blocks	Add "Janusian Intent" sections to explain purpose
💻 Code Blocks	Use real SQL / shell / markdown examples
🔗 Cross-links	Use relative paths: [See thread states](../states.md)
🔒 Access Hints	Use visibility to mark human vs. agent-readable

---

📌 Final Summary

Your RAG-ready Janusian doc system will be:

• 🔍 Searchable by humans and AI
• 🧱 Modular, well-scoped, chunkable
• 🏷️ Metadata-rich, with project, version, intent, and role info
• 🧠 Philosophically aligned with human-AI co-development
• 💡 Designed to scale, as agents and tooling grow

---