An environment for inquiry - complete documentation
Documentation for Veritheia isn’t just technical reference—it’s part of the epistemic infrastructure itself. Clear documentation ensures that contributors understand not just what to build but why each piece matters for user sovereignty. Every word written should strengthen the principle that Veritheia enables formation through authorship, where users develop understanding through structured engagement with their documents, not through consumption of AI-generated outputs.
Veritheia embraces specification-first development where complete documentation precedes implementation. This isn’t bureaucratic overhead—it’s architectural discipline. The specifications in /docs define the system’s philosophical commitments and technical contracts. Implementation follows specification, never the reverse.
Why this matters: When specifications are complete before code is written, architectural drift becomes impossible. The system can evolve incrementally while maintaining coherence with its founding principles. Every implementation decision traces back to documented reasoning. Every technical choice serves the documented purpose of enabling formation through authorship.
Documentation should read as prose with embedded reasoning, not bullet-pointed specifications. When you explain a technical concept, show the thinking that led to it.
For instance, rather than listing “PostgreSQL with pgvector” as a choice, explain that PostgreSQL with pgvector provides unified storage for documents and embeddings within the same ACID boundary, eliminating synchronization complexity while enabling semantic search as a first-class domain operation. This isn’t verbose—it’s transparent reasoning.
Poor:
Better: “The system employs PostgreSQL as an Object-Relational Database Management System (ORDBMS), leveraging its full capabilities rather than treating it as a simple data store. PostgreSQL’s pgvector extension provides semantic search through high-dimensional vector operations, indexed using Hierarchical Navigable Small World (HNSW) graphs for logarithmic query complexity even at scale. This unified approach eliminates the synchronization complexity that would arise from separating relational, document, and vector stores into distinct systems.”
The second version explains not just what but why, embedding the reasoning directly in the prose.
Formation Notes connect technical features to user authorship. These aren’t decorative additions but essential bridges between mechanism and purpose. Format them as blockquotes beginning with “> Formation Note:”
Add Formation Notes when:
Formation Note: The composite primary keys (UserId, Id) aren’t just partitioning—they’re sovereignty boundaries ensuring your intellectual work remains yours. When PostgreSQL rejects a Journey without a Persona, it’s protecting a truth we’ve discovered: every inquiry requires a perspective.
Formation Notes should appear immediately after technical explanations to ground them in purpose.
Every document serves multiple audiences: developers implementing features, users understanding capabilities, and contributors grasping philosophy. Balance these needs through layered explanation.
Start with purpose (why this matters for formation), then explain the concept (what it does for users), then provide technical detail (how it’s implemented). This progression serves all audiences without sacrificing precision.
“Journey projection spaces enable users to engage with thousands of documents through their own intellectual lens. When documents enter a journey, they’re not stored generically but projected into that journey’s intellectual space—a systematic review projects documents through methodology sections and research questions, while an educational journey projects the same documents through learning objectives and rubrics. Technically, this is implemented through the journey_document_segments table where documents are segmented according to journey-specific rules stored in journey_frameworks, with embeddings generated using the journey’s conceptual vocabulary as context.”
No technical decision exists in isolation. Every choice—from database schema to API design—must trace back to enabling formation through authorship.
When documenting technical decisions:
“The Process Engine implements neurosymbolic architecture, transcended, by mechanically orchestrating the systematic application of user-authored symbolic frameworks through neural semantic understanding. This ensures that ALL documents receive identical treatment—the engine mechanically processes every document without LLM judgment about which documents are ‘worth’ processing. This mechanical fairness is essential for formation: users must engage with systematically processed documents, not AI-curated selections.”
/docs)Public documentation defines the complete specification of Veritheia. These documents:
Public documentation should be complete, coherent, and compelling. It presents Veritheia as fully-conceived epistemic infrastructure, even when implementation is ongoing.
/development)Development documentation tracks implementation progress and journeys. These documents:
Development documentation can be messier, showing work-in-progress and recording dead ends that informed better approaches.
When development docs need to reference specifications, link to /docs rather than duplicating content. When public docs need to acknowledge implementation status, use priority markers rather than detailed progress reports.
Every major document should include:
Don’t:
Do:
Documents are numbered to enforce proper reading order:
Numbers create a suggested path while allowing selective reading. A developer implementing a feature might read 01-VISION for context, jump to 07-ENTITY-RELATIONSHIP for schema, then 10-DESIGN-PATTERNS for implementation patterns.
Emphasize what they can do and how it preserves their intellectual sovereignty. Avoid implementation details. Focus on capability and agency.
Example: “Your research questions shape what documents mean within your journey. The same paper that seems irrelevant to a broad query becomes essential when viewed through your specific theoretical lens.”
Provide precise technical detail while maintaining connection to purpose. Include code examples and specific patterns.
Example: “Implement composite primary keys (UserId, Id) using UUIDv7 via Guid.CreateVersion7() for partition enforcement and temporal ordering. This ensures queries naturally scope to user partitions while maintaining temporal sequence without external sequence management.”
Explain both philosophy and mechanism. Show how architectural decisions embody philosophical commitments.
Example: “We reject the Repository pattern not from ignorance but from recognition that PostgreSQL IS our domain model. The schema embodies business rules through constraints. To abstract it would be to deny its participation in domain modeling.”
After making documentation updates, perform this recursive review:
Documentation for Veritheia is living documentation—it evolves with understanding while maintaining philosophical coherence. When you discover better ways to explain concepts, update the documentation. When implementation reveals new insights, reflect them in specifications. When user feedback clarifies purpose, strengthen the vision.
The documentation is never “done” but rather continuously refined to better serve its purpose: ensuring that everyone who encounters Veritheia understands that it enables formation through authorship, where users develop understanding through structured engagement with their documents, guided by their questions, shaped by their framework.
Every word you write in Veritheia’s documentation should serve the principle that users author their own understanding. If a sentence doesn’t ultimately connect to user sovereignty, intellectual formation, or epistemic infrastructure, it probably doesn’t belong.
The documentation isn’t just describing software; it’s preserving the possibility of genuine user understanding in an age of AI-generated content. Write accordingly.
This guide itself demonstrates the principles it espouses: prose with embedded reasoning, Formation Notes at key moments, and constant connection back to the purpose of enabling formation through authorship.