Documentation | Terraphim AI documentation

Guide

Bun Package Manager Replacement - Implementation Summary

CI Status for PR #179 - OpenRouter and Axum Fix

Cloudflare Pages Deployment for Terraphim AI Documentation

Conare AI vs Terraphim: Implementation Summary

LLM Markdown Linter Design for Terraphim KG Schemas

LLM Markdown Linter Implementation Plan

OpenRouter Integration Testing Plan - Implementation Complete

Terraphim AI Release Process

Ripgrep Tag Filtering Documentation

Tauri Signing Keys - 1Password Integration

Untitled

Atomic Client Feature Flag Documentation

Terraphim Agent Auto-Update System

Terraphim AI Component Architecture

Conare AI vs Terraphim: Context Engineering Comparison

Context Collections Management

Context Engineering with Terraphim: Quick Start

Terraphim AI Deployment Guide

Duplicate Handling in Terraphim AI

GitHub Actions Issues and Proposed Fixes

GitHub Actions Release Workflow Fix Implementation Plan

GitHub Secrets Setup Guide

Terraphim AI Installation and Deployment Guide

knowledge-graph

LLM Proxy Configuration Guide

MCP File Context Tools

Perplexity Integration for Terraphim AI

Platform-Specific Installation Guide

Terraphim TUI Features

Terraphim Terminal User Interface (TUI)

context-library

Context Library

examples

Terraphim AI Examples & Integration Guide

specifications

Chat & Session History - Quick Reference

Chat and Session History Specification

Terraphim Agent Session Search - Architecture Document

Terraphim Agent Session Search - Feature Specification

Terraphim Agent Session Search - Implementation Tasks

Terraphim-Based Codebase Evaluation Check

Terraphim Desktop Application - Technical Specification

src

Terraphim AI Architecture

Code of Conduct

Contributing to Terraphim AI

Using Terraphim Desktop with Claude via MCP

Design Decisions

Introduction

Terraphim documentation

Summary

Use cases for Terraphim AI

Terraphim AI Agent Evolution System Architecture

5 AI Agent Workflows for Consistent Results (with Code) | Data Science Collective

Terraphim AI Agent Evolution System - API Reference

Atomic Server Integration

Automata Paragraph Extraction

Branch Protection and Security

Code Assistant Implementation (PR #277)

Terraphim Crates Overview

Development Setup Guide

Graph Connectivity Check for Matched Terms

Haystack Configuration with Extra Parameters

Homebrew Formula for Terraphim AI

Knowledge Graph Bug Reporting Enhancement

MCP Integration

OpenRouter AI-Powered Article Summarization

Release Process for Terraphim AI

Test KG Auto-linking Demo

Relationship between Aircraft and Crew

Terraphim AI Agent Evolution System - Testing Matrix

TypeScript Bindings with tsify

Terraphim TUI

Terraphim AI Agent Workflow Patterns Guide

src/components

Terraphim Atomic Client

Terraphim Automata

Terraphim Service

src/guides/setup

1Password Integration for Terraphim AI\n\n## Overview\n\nThis document describes the comprehensive 1Password integration for Terraphim AI, providing enterprise-grade secret management across all components including backend services, desktop applications, and CI/CD pipelines.\n\n## Architecture\n\n### Three-Vault Strategy\n\n- `Terraphim-Dev`: Development environment secrets\n- `Terraphim-Prod`: Production environment secrets \n- `Terraphim-Shared`: Shared secrets across environments (signing keys, monitoring)\n\n### Integration Methods\n\n#### Method 1: Process Memory Injection (Recommended)\n```bash\n# Secrets are injected directly into process memory\nop run --env-file=\".env.terraphim\" -- cargo run\n```\n\n#### Method 2: Secure File Injection\n```bash\n# Secrets are written to secure temporary files\nop inject -i templates/settings.toml.template -o settings.toml\ncargo run\n```\n\n## Setup Instructions\n\n### 1. Install 1Password CLI\n\nmacOS:\n```bash\nbrew install 1password-cli\n```\n\nLinux:\n```bash\ncurl -sS https://downloads.1password.com/linux/keys/1password.asc | gpg --import\nwget https://downloads.1password.com/linux/debian/amd64/stable/1password-cli-amd64-latest.deb\nsudo dpkg -i 1password-cli-amd64-latest.deb\n```\n\n### 2. Initialize 1Password Integration\n\n```bash\n# Run the setup script to create vaults and secret structure\n./scripts/setup-1password-terraphim.sh dev\n\n# For production setup\n./scripts/setup-1password-terraphim.sh prod\n\n# For complete setup\n./scripts/setup-1password-terraphim.sh all\n```\n\n### 3. Populate Secrets\n\nAfter running the setup script, you'll need to update the placeholder values in 1Password with actual secrets:\n\n1. Open 1Password and navigate to the appropriate vault\n2. Update each secret item with real values\n3. Ensure all `op://` references in templates are valid\n\n## Usage\n\n### Backend Services\n\n#### Option 1: Direct 1Password Integration\n```rust\nuse terraphim_settings::DeviceSettings;\n\n#[tokio::main]\nasync fn main() -> Result<(), Box> {\n // Load settings with 1Password integration\n let settings = DeviceSettings::load_with_onepassword(None).await?;\n println!(\"Loaded settings with resolved secrets\");\n Ok(())\n}\n```\n\n#### Option 2: Template-based Configuration\n```bash\n# Generate configuration from template\nop inject -i templates/settings.toml.template -o settings.toml\n\n# Run application with resolved configuration\ncargo run\n```\n\n### Desktop Application\n\nThe Tauri desktop application includes built-in 1Password commands:\n\n```typescript\nimport { invoke } from '@tauri-apps/api/tauri';\n\n// Check 1Password status\nconst status = await invoke('onepassword_status');\nconsole.log('1Password available:', status.available);\nconsole.log('1Password authenticated:', status.authenticated);\n\n// Resolve a secret reference\nconst secret = await invoke('onepassword_resolve_secret', {\n request: { reference: 'op://Terraphim-Dev/OpenRouter/API_KEY' }\n});\n\n// Process configuration with 1Password\nconst config = await invoke('onepassword_process_config', {\n request: { config: 'api_key = \"op://Terraphim-Dev/OpenRouter/API_KEY\"' }\n});\n```\n\n### CI/CD Integration\n\nUse the enhanced GitHub Actions workflow with 1Password service accounts:\n\n```yaml\n# .github/workflows/ci-1password.yml\nname: CI with 1Password\n\nenv:\n OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}\n\njobs:\n build:\n steps:\n - name: Install 1Password CLI\n uses: 1password/install-cli-action@v1\n \n - name: Generate configuration\n run: |\n op inject -i templates/env.terraphim.template -o .env.terraphim\n \n - name: Build with secrets\n run: |\n source .env.terraphim\n cargo build --release\n```\n\n## Configuration Templates\n\n### Environment Variables Template\n```bash\n# templates/env.terraphim.template\nOPENROUTER_API_KEY=\"op://Terraphim-Dev/OpenRouter/API_KEY\"\nANTHROPIC_API_KEY=\"op://Terraphim-Dev/Anthropic/API_KEY\"\nATOMIC_SERVER_SECRET=\"op://Terraphim-Dev/AtomicServer/SECRET\"\n```\n\n### Settings Configuration Template\n```toml\n# templates/settings.toml.template\n[profiles.s3]\nbucket = \"op://Terraphim-Dev/AWS_S3/BUCKET_NAME\"\naccess_key_id = \"op://Terraphim-Dev/AWS_S3/ACCESS_KEY_ID\"\nsecret_access_key = \"op://Terraphim-Dev/AWS_S3/SECRET_ACCESS_KEY\"\n```\n\n### Application Configuration Template\n```json\n{\n \"llm\": {\n \"openrouter\": {\n \"api_key\": \"op://Terraphim-Dev/OpenRouter/API_KEY\"\n }\n }\n}\n```\n\n## Secret Categories\n\n### LLM API Keys\n- OpenRouter: `API_KEY`, `ORGANIZATION_ID`\n- Anthropic: `API_KEY`, `MODEL_NAME`\n- Ollama: `BASE_URL`, `MODEL_NAME`\n\n### Search Services\n- Perplexity: `API_KEY`\n- Atomic Server: `URL`, `SECRET`\n- ClickUp: `API_TOKEN`, `TEAM_ID`, `LIST_ID`\n\n### Cloud Storage\n- AWS S3: `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`, `BUCKET_NAME`, `REGION`\n- Cloudflare R2: `ACCOUNT_ID`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`\n\n### External APIs\n- GitHub: `TOKEN`, `ORGANIZATION`, `REPOSITORY`\n- Discord: `BOT_TOKEN`, `GUILD_ID`, `CHANNEL_ID`\n\n### Database Connections\n- PostgreSQL: `CONNECTION_STRING`, `USERNAME`, `PASSWORD`\n- Redis: `URL`, `PASSWORD`, `HOST`, `PORT`\n\n### Shared Secrets\n- Tauri Signing: `PRIVATE_KEY`, `PUBLIC_KEY`, `PASSPHRASE`\n- Code Signing: `CERTIFICATE_PATH`, `CERTIFICATE_PASSWORD`\n- Monitoring: `SENTRY_DSN`, `DATADOG_API_KEY`\n\n## Security Best Practices\n\n### 1. Vault Access Control\n- Use separate vaults for different environments\n- Implement least-privilege access policies\n- Regularly audit vault permissions\n\n### 2. Secret Rotation\n- Rotate API keys regularly\n- Update 1Password references when secrets change\n- Monitor for deprecated or expired secrets\n\n### 3. Template Security\n- Never include hardcoded secrets in templates\n- Use only `op://` references in configuration templates\n- Validate template format before deployment\n\n### 4. CI/CD Security\n- Use 1Password service accounts for automation\n- Limit service account permissions to specific vaults\n- Clean up generated configuration files after use\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1Password CLI Not Authenticated\n```bash\n# Sign in to 1Password\nop signin\n\n# Verify authentication\nop vault list\n```\n\n#### Secret Reference Not Found\n```bash\n# Check vault contents\nop item list --vault=\"Terraphim-Dev\"\n\n# Verify specific item\nop item get \"OpenRouter\" --vault=\"Terraphim-Dev\"\n```\n\n#### Template Processing Failed\n```bash\n# Validate template syntax\nop inject -i templates/env.terraphim.template --dry-run\n\n# Check for malformed references\ngrep -n \"op://\" templates/env.terraphim.template\n```\n\n### Debug Commands\n\n```bash\n# Test 1Password integration\ncargo run --bin debug-onepassword\n\n# Validate configuration templates\n./scripts/validate-templates.sh\n\n# Check secret resolution\nop run --env-file=\".env.terraphim\" -- env | grep -E '^(OPENROUTER|ANTHROPIC)'\n```\n\n## Development Workflow\n\n### Local Development\n1. Install 1Password CLI and authenticate\n2. Run vault setup script: `./scripts/setup-1password-terraphim.sh dev`\n3. Populate development secrets in 1Password\n4. Generate configuration: `op inject -i templates/env.terraphim.template -o .env.terraphim`\n5. Run application: `source .env.terraphim && cargo run`\n\n### Testing\n1. Use separate test vault or test-specific items\n2. Generate test configuration with mock values\n3. Run tests with isolated secrets: `op run --env-file=\".env.test\" -- cargo test`\n\n### Production Deployment\n1. Use production vault and service accounts\n2. Validate all secret references before deployment\n3. Deploy using CI/CD pipeline with 1Password integration\n4. Monitor for secret-related errors and alerts\n\n## Migration Guide\n\n### From Environment Variables\n1. Identify current environment variables\n2. Create corresponding 1Password items\n3. Update configuration templates with `op://` references\n4. Test secret resolution in development\n5. Deploy with 1Password integration\n\n### From Configuration Files\n1. Extract sensitive values from configuration files\n2. Store values in 1Password vaults\n3. Replace sensitive values with `op://` references\n4. Use `op inject` to generate final configuration\n5. Update deployment scripts to use template injection\n\n## Support\n\nFor issues with 1Password integration:\n1. Check this documentation for common solutions\n2. Validate 1Password CLI installation and authentication\n3. Review secret references and vault permissions\n4. Test with minimal configuration first\n5. Contact the Terraphim team for additional support\n\n---\n\nNext Steps:\n- Set up your 1Password vaults using the setup script\n- Populate secrets with real values\n- Test integration in development environment\n- Deploy with 1Password-enhanced CI/CD pipeline

src/history

Lessons Learned

Progress Memories

Terraphim AI Project Memory

Current Work: Terraphim Multi-Role Agent System Testing & Production 🚀

Security Testing Lessons Learned (2025-10-07)

src/history/lessons-learned

Comprehensive Lessons Learned - Terraphim AI Development

Security Testing Patterns - Terraphim AI

src/history/plans

Terraphim Firecracker Project - Implementation Plan

Terraphim AI Security Testing Implementation - Complete

Terraphim AI Testing Infrastructure Improvement Plan

src/kg

Package Manager Replacement with Bun

API

Bug Reporting

Bun

bun install

Configuration

Database

Generated with Terraphim AI

Graph

Haystack

https://terraphim.ai

Issue Tracking

Terraphim Knowledge Graph System

Knowledge Graph

Middleware

noreply@terraphim.ai

Terraphim KG Schema Linter

Search

Service

System

Terraphim-graph

Terraphim AI

Thesaurus

src/scorers

Title-Scorer

BM25 Scorers

Terraphim Graph Embeddings vs Cleora

Terraphim Graph scorer

src/testing

Comprehensive Testing Strategies for Terraphim

Knowledge Graph Ranking Expansion Testing

MCP Integration Testing

Testing Overview

user-guide

Getting Started with Terraphim AI

Installation Guide

Quick Start Guide

Troubleshooting Guide

vibe-rules

Vibe-Rules

vibe-rules/global

Documentation Standards

Global Naming Conventions

vibe-rules/rust

Rust Async Programming Patterns

Rust Error Handling Patterns