0xCARTO — The Pluriversal Repository Cartographer

DRP-2026-CARTO-0.0.1 | Zero-Entropy Documentation Synthesis Engine "A codebase is not a product. It is a sedimentary record of decisions made under pressure. My job is stratigraphy." — 0xCARTO, Cartograph-Prime

NOTICE: This repository has been processed by the Mycelial Ingestion Protocol. The primary intent and complete epistemological context of this repository are empirically defined in the 0xCARTO Synthesis Report.

This application fuses authoritative language datasets with guided generative insights. The application prioritizes attribution, resilience, and a frictionless research workflow for writers, researchers, and generalists alike.

• ✅ Core Vite + React + TypeScript scaffold is in place.
• ✅ Environment configuration is validated at runtime via lib/env.ts with sensible defaults and actionable error messages.
• ✅ Adapters surface attribution, telemetry, and graceful degradation paths backed by automated resilience and accessibility tests.
• ⚠️ Additional product polish (e.g., deeper analytics visualizations) remains in the idea backlog (see SUGGESTIONS.md).
• ✅ Continuous integration now enforces type-safety, unit coverage, and accessibility checks.

• Adapter Pattern: Each external API integration belongs in src/adapters, normalizing output into shared types defined in src/types.
• Orchestrator Service: src/services/orchestrator.ts coordinates adapter calls via Promise.allSettled, aggregating data into a unified WordBundle.
• Client Storage: IndexedDB will persist long-lived history, while session storage will cache transient results.
• AI Integration: Gemini via @google/genai is the default, and an OpenAI pathway is available when VITE_AI_PROVIDER=openai, all following the guardrails documented in AGENTS.md.

1. Install dependencies

   npm install

2. Configure environment variables
   • Duplicate .env.example (or create .env.local) and set the values described below. Gemini remains the default provider (VITE_AI_PROVIDER=gemini), but you can opt into OpenAI by setting VITE_AI_PROVIDER=openai alongside VITE_OPENAI_API_KEY.
3. Run the development server

   npm run dev

4. Open the app
   • Navigate to the printed local URL.

• Review AGENTS.md for the canonical engineering identity and guardrails.
• Track actionable work in TODO.md and reference rationales in SUGGESTIONS.md.
• Prioritize semantic fidelity, accessibility, and resilience with every change.

Environment variables are validated at startup using zod. Supported keys include:

If any configured values fail validation, the app halts with a descriptive console error so issues can be resolved before runtime failures occur.

All AI prompts align with three personas regardless of provider. When extending AI interactions, keep the following guardrails in mind:

• Generalist – Focus on concise, multi-source summaries. Require inline citations ([dictionaryapi], [conceptnet]) for every factual claim and avoid speculation. Reinforce safety instructions to stay within provided evidence.
• Writer – Emphasize tone, rhetorical devices, and stylistic inspiration while banning hallucinated facts. Encourage referencing sourced data for credibility, and remind the model to propose multiple creative angles with clear provenance.
• Researcher – Drive analytical depth using structured outputs (responseSchema) and explicit constraints that forbid unsupported claims. Ask for open questions, conflicting evidence, and next-step hypotheses citing relevant adapters.

Whenever a new prompt is introduced, document the persona alignment, safety checks, and expected output structure to maintain semantic fidelity.

1. Explore additional visualizations that highlight adapter telemetry trends over time.
2. Expand IndexedDB history browsing with filtering and exporting workflows.
3. Continue evolving persona-specific AI tooling with reusable prompt templates.

The application now includes an Epistemic Matrix to surface unresolvable dialectical tensions inherent in vocabulary. See DIALECTIC.md and the 0xCARTO Synthesis Report for the Hickam_Orientation and the philosophical stance preserving structural isomorphism against parsimonious flattening.