Environment Setup & Workspaces

Relevant source files

The following files were used as context for generating this wiki page:

• [- gitbook.com -.md](https://github.com/LAF-US/IDAHO-VAULT/blob/5776c621c261e34d84b86cd7a19749a3e9f28f9c/- gitbook.com -.md)
• VAULT-CONVENTIONS.from-pushable-2026-05-08.md
• DEPENDENCY_RESOLUTION_PLAN.md
• backup-compare-temp/CREWAI/HANDOFF-CREWAI-OPS.md
• IDAHO-VAULT — WORKFLOW.md
• - When to Use OpenHands.md

The IDAHO-VAULT environment is a hybrid system designed for journalism research, combining local Obsidian-based knowledge management with automated AI-driven workflows. The environment is architected to be platform-agnostic, supporting Windows (NTFS), macOS (APFS/HFS+), and Linux (ext4) to ensure cross-environment runtime portability. The setup prioritizes a "local-first" approach for data privacy while utilizing GitHub Actions for transport and automated tasks.

This workspace facilitates the transformation of raw information—such as bills, transcripts, and datasets—into structured, interpreted, and verified journalistic content. It integrates various agentic frameworks like CrewAI and GitBook for documentation, ensuring that all committed content is on the record and publishable.

Sources: VAULT-CONVENTIONS.from-pushable-2026-05-08.md:20-30, IDAHO-VAULT — WORKFLOW.md:12-25, VAULT-CONVENTIONS.from-pushable-2026-05-08.md:435-445

Workspace Architecture & Portability

The project adheres to the NETWEB standard, ensuring the vault works identically across different operating systems. This is critical because of the differing ways filesystems handle case sensitivity and reserved names.

Runtime Portability Standard (MESHWEB)

The environment defines specific capabilities for local CLI, cloud instances, and GitHub Actions CI. It utilizes a MESHWEB Registry to track environment-scoped artifacts and gaps.

Filesystem Constraints

To maintain compatibility across NTFS (Windows) and APFS/HFS+ (macOS), the workspace enforces a case-insensitive baseline and restricts the use of specific characters and reserved names.

Constraint	Requirement
Reserved Names	Forbidden: AUX, CON, NUL, PRN, COM0-9, LPT0-9.
Aliasing	Use _ prefix (e.g., _AUX.md) and add aliases: [ORIGINAL] to frontmatter.
Path Patterns	No trailing periods or spaces; no chars `< > : "
Path Length	Max 218 characters from repo root to accommodate NTFS limits.

Sources: VAULT-CONVENTIONS.from-pushable-2026-05-08.md:430-480

Environment Component Flow

The following diagram illustrates how different environments interact with the core vault content:

Setup & Dependency Management

The workspace utilizes uv and Python virtual environments to manage a complex stack of over 400 dependencies.

Core Prerequisites

• Python 3.13+: Required for the execution layer.
• Virtual Environment: A .venv must be active at the vault root.
• System Libraries: Certain dependencies, such as simdutf (Unicode library) and lancedb (Vector database), require system-level installation or building from source depending on the OS (e.g., macOS 12 limitations).

Sources: backup-compare-temp/CREWAI/HANDOFF-CREWAI-OPS.md:12-25, DEPENDENCY_RESOLUTION_PLAN.md:15-40

Initialization Commands

# Activate environment (Linux/macOS)
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start-up validation
python scripts/validate_bootstrap.py

Sources: backup-compare-temp/CREWAI/HANDOFF-CREWAI-OPS.md:12-20, DEPENDENCY_RESOLUTION_PLAN.md:65-70

Configuration & Secret Management

Secrets are never hardcoded or stored directly in GitHub Secrets. The project uses 1Password as a centralized secret manager.

• OP_SERVICE_ACCOUNT_TOKEN: The only secret stored in GitHub, used to fetch all other credentials at runtime.
• Workflow Access: Workflows use op item get to retrieve API keys (e.g., ANTHROPIC_API_KEY) dynamically.
• Git Security: Developers use the 1Password SSH agent for local authentication and Git signing.

Sources: VAULT-CONVENTIONS.from-pushable-2026-05-08.md:315-350, backup-compare-temp/CREWAI/HANDOFF-CREWAI-OPS.md:22-30

GitBook & Documentation Structure

Documentation is managed using GitBook through a Git-synced repository. This allows for local editing in editors like Cursor or Claude Code while maintaining a structured output.

Configuration (.gitbook.yaml)

The .gitbook.yaml file defines the root of documentation and the location of the README.md (homepage) and SUMMARY.md (table of contents).

root: ./
structure:
  readme: ./README.md
  summary: ./SUMMARY.md
redirects:
  old-page: new-page.md

Sources: - gitbook.com -.md:125-145

GitBook Block Types

Need	Block Syntax
Sequential instructions	{% stepper %}
Callouts/Warnings	{% hint style="..." %}
Expandable content	<details>
Code Tabs	{% tabs %}

Sources: - gitbook.com -.md:55-80

AI Agent Workspaces (OpenHands & CrewAI)

The environment integrates specific AI frameworks to handle different levels of task complexity.

OpenHands Workspace

OpenHands is used for code-related tasks within a sandbox. Its effectiveness depends on repository preparation:

• Clean State: All changes committed before starting.
• AGENTS.md: A required checklist file in the root containing build/test commands and architecture overviews.
• Scope: Ideal for tasks under 100 lines of code with clear success criteria.

Sources: - When to Use OpenHands.md:75-90, - When to Use OpenHands.md:135-155

CrewAI Operations

CrewAI agents operate in a staging area within the vault under the !/CREWAI/ directory.

Summary

Environment setup in IDAHO-VAULT requires strict adherence to the NETWEB portability standards and 1Password secret management protocols. By utilizing a local-first virtual environment combined with Git-synced documentation and agent-specific sandboxes (OpenHands, CrewAI), the system ensures that complex journalistic data is transformed reliably while maintaining a strict audit trail and platform independence.