Initial commit containing architetural scaffolding and mvp

.thoth/00-project-state.md

@@ -0,0 +1,31 @@
+Current Version
+
+0.0.1
+
+Current Focus
+
+ChatGPT Capture Connector
+
+Completed
+
+✓ Reference Architecture
+
+✓ ADR-001
+
+✓ ADR-002
+
+✓ ADR-003
+
+✓ Metadata Generator
+
+In Progress
+
+• Capture Service
+
+Blocked
+
+• Browser Extension
+
+Next Milestone
+
+Capture MVP

.thoth/10-architecture.md

@@ -0,0 +1,341 @@
+# Project Thoth Architecture
+
+**Version:** 1.0  
+**Status:** Living Document
+
+---
+
+# Purpose
+
+This document describes the canonical architecture of Project Thoth.
+
+It is intended to answer a single question:
+
+> **How does information flow through the Project Thoth ecosystem?**
+
+This document describes architecture, not implementation.
+
+Current implementation status is maintained separately in `.thoth/00-project-state.md`.
+
+---
+
+# Architectural Principles
+
+Project Thoth is built upon the following principles:
+
+- Source artifacts are permanent.
+- Generated artifacts are disposable.
+- Every transformation is deterministic.
+- AI providers are interchangeable.
+- Markdown is the canonical document format.
+- Knowledge is owned by the archive, not the AI.
+- Processing stages should be loosely coupled.
+- Every stage should be independently testable.
+
+---
+
+# High-Level Architecture
+
+```
+                External Sources
+                       │
+                       ▼
+             Capture Connectors
+                       │
+                       ▼
+            Canonical Source Archive
+                       │
+                       ▼
+                Processing Pipeline
+                       │
+        ┌──────────────┼──────────────┐
+        ▼              ▼              ▼
+   Metadata       Manifest       Harvests
+   Generation     Generation     Generation
+        │              │              │
+        └──────────────┼──────────────┘
+                       ▼
+              Knowledge Repository
+                       │
+                       ▼
+             Search / Retrieval Layer
+                       │
+                       ▼
+                  AI Consumers
+```
+
+---
+
+# Layers
+
+## 1. External Sources
+
+Project Thoth captures knowledge from external systems.
+
+Examples include:
+
+- ChatGPT
+- Claude
+- Gemini
+- Microsoft Copilot
+- Open WebUI
+- Local LLMs
+- Documentation systems
+- Markdown repositories
+- Future knowledge sources
+
+These systems are considered transient.
+
+They are never considered the canonical repository.
+
+---
+
+## 2. Capture Connectors
+
+Capture Connectors preserve source material.
+
+Responsibilities include:
+
+- Capture conversations
+- Preserve ordering
+- Preserve formatting
+- Preserve attachments
+- Produce canonical source documents
+
+Capture Connectors do **not**:
+
+- Summarize
+- Interpret
+- Classify
+- Generate metadata
+- Perform AI reasoning
+
+They are intentionally deterministic.
+
+---
+
+## 3. Canonical Source Archive
+
+The archive contains the preserved source material.
+
+Typical artifacts include:
+
+- conversation.md
+- source assets
+- attachments
+
+The archive is immutable.
+
+Once source material has been captured it should not be modified.
+
+If processing changes in the future, artifacts are regenerated from the archived source.
+
+---
+
+## 4. Processing Pipeline
+
+Processors transform source artifacts into derived artifacts.
+
+Typical processors include:
+
+- Metadata generation
+- Manifest generation
+- Harvest generation
+- Search indexing
+- Embedding generation
+
+Processors never modify source artifacts.
+
+They only generate derived artifacts.
+
+---
+
+## 5. Knowledge Repository
+
+The repository contains:
+
+- Source artifacts
+- Derived artifacts
+- Metadata
+- Relationships
+
+This becomes the canonical knowledge base for Project Thoth.
+
+---
+
+## 6. Consumers
+
+Consumers interact with the repository.
+
+Examples:
+
+- Local LLMs
+- Search engines
+- Knowledge assistants
+- Documentation systems
+- Human readers
+
+Consumers should never depend on the original AI platform.
+
+---
+
+# Capture Connector Architecture
+
+Every Capture Connector implements the same logical pipeline.
+
+```
+Optional Preprocessing
+          │
+          ▼
+Conversation Discovery
+          │
+          ▼
+Intermediate Representation
+          │
+          ▼
+Content Transformation
+          │
+          ▼
+Markdown Serialization
+          │
+          ▼
+conversation.md
+```
+
+This architecture is defined by ADR-002.
+
+Only the Discovery stage is expected to be platform-specific.
+
+---
+
+# Processing Philosophy
+
+Project Thoth separates preservation from interpretation.
+
+```
+Capture Once
+
+↓
+
+Preserve Forever
+
+↓
+
+Process Many Times
+```
+
+This allows improvements to processors without requiring the original source to be recaptured.
+
+---
+
+# Canonical Artifacts
+
+Project Thoth distinguishes between canonical artifacts and generated artifacts.
+
+## Canonical
+
+Examples:
+
+- conversation.md
+- Source attachments
+- Images
+- Audio
+- Video
+
+Canonical artifacts are permanent.
+
+---
+
+## Generated
+
+Examples:
+
+- Metadata
+- Manifests
+- Harvests
+- Embeddings
+- Search indexes
+
+Generated artifacts may be deleted and regenerated at any time.
+
+---
+
+# Repository Structure
+
+A typical Project Thoth repository contains:
+
+```
+.thoth/
+    Project self-description
+
+applications/
+    Executable applications
+
+processors/
+    Artifact processors
+
+specifications/
+    Canonical document specifications
+
+docs/
+    Architecture and ADRs
+
+codex/
+    Engineering work orders
+
+archive/
+    Captured source material
+
+generated/
+    Derived artifacts
+```
+
+Implementation details may evolve while preserving the architectural boundaries described in this document.
+
+---
+
+# Architectural Boundaries
+
+Each layer has a single responsibility.
+
+| Layer | Responsibility |
+|---------|----------------|
+| Capture Connectors | Preserve source material |
+| Archive | Store canonical source |
+| Processors | Generate derived artifacts |
+| Repository | Organize knowledge |
+| Consumers | Read knowledge |
+
+No layer should assume the responsibilities of another.
+
+---
+
+# Design Goals
+
+The architecture is intended to achieve:
+
+- Long-term preservation
+- Platform independence
+- Deterministic processing
+- Reproducibility
+- Testability
+- Portability
+- AI interoperability
+
+---
+
+# Relationship to Other Documents
+
+This document defines **how Project Thoth is organized**.
+
+Related documents include:
+
+- **00-project-state.md** — Current implementation status.
+- **20-philosophy.md** — Guiding principles.
+- **30-glossary.md** — Canonical terminology.
+- **40-coding-standards.md** — Development standards.
+- **ADR-001** — Project structure.
+- **ADR-002** — Capture connector pipeline.
+- **ADR-003** — Capture connector architecture.
+
+Together these documents form the canonical self-description of the project.

.thoth/20-philosophy.md

@@ -0,0 +1,321 @@
+# Project Thoth Philosophy
+
+**Version:** 1.0  
+**Status:** Living Document
+
+---
+
+# Purpose
+
+Project Thoth is founded on a simple belief:
+
+> **Knowledge should outlive the systems that create it.**
+
+Artificial intelligence systems, software platforms, file formats, and vendors will continue to evolve.
+
+Human knowledge should not depend on any of them.
+
+Project Thoth exists to preserve human reasoning in a portable, deterministic, and vendor-independent form.
+
+---
+
+# Core Philosophy
+
+Project Thoth is not an AI project.
+
+It is a knowledge preservation project that happens to use AI.
+
+Artificial intelligence is a consumer of knowledge, not its owner.
+
+The archive is the product.
+
+Everything else is replaceable.
+
+---
+
+# Guiding Principles
+
+## 1. The Archive is Canonical
+
+The archive is the source of truth.
+
+Not ChatGPT.
+
+Not Claude.
+
+Not Gemini.
+
+Not a vector database.
+
+Not an embedding model.
+
+Every generated artifact should be reproducible from the archive.
+
+---
+
+## 2. Source Artifacts are Permanent
+
+Original captured material should never be destroyed.
+
+Examples include:
+
+- Conversations
+- Images
+- Audio
+- Video
+- Attachments
+
+Source artifacts represent historical evidence.
+
+They cannot be recreated once lost.
+
+---
+
+## 3. Generated Artifacts are Disposable
+
+Metadata.
+
+Embeddings.
+
+Search indexes.
+
+Harvests.
+
+Summaries.
+
+These exist only to improve access to the archive.
+
+They should always be considered disposable.
+
+If a better algorithm is developed tomorrow, they should simply be regenerated.
+
+---
+
+## 4. Capture Once. Process Forever.
+
+Knowledge capture should occur only once.
+
+Processing should occur as many times as necessary.
+
+New processors should never require recollecting historical conversations.
+
+---
+
+## 5. Determinism Over Magic
+
+Project Thoth prefers deterministic transformations over opaque intelligence.
+
+The same input should produce the same output.
+
+When AI reasoning is introduced, it should be clearly separated from preservation.
+
+---
+
+## 6. AI Providers are Interchangeable
+
+No AI vendor should become part of the archive.
+
+ChatGPT.
+
+Claude.
+
+Gemini.
+
+Copilot.
+
+Open WebUI.
+
+Future models.
+
+These are simply sources of knowledge.
+
+The archive must remain usable regardless of which systems disappear.
+
+---
+
+## 7. Markdown is the Universal Language
+
+Project Thoth prefers open, human-readable formats.
+
+Markdown provides:
+
+- longevity
+- portability
+- version control
+- interoperability
+- readability
+
+Whenever practical, proprietary formats should be transformed into Markdown.
+
+---
+
+## 8. Knowledge Should be Human-Readable
+
+Every canonical artifact should be understandable without specialized software.
+
+A person should be able to browse the archive with nothing more than a text editor.
+
+Software enhances the archive.
+
+It should never become a prerequisite for understanding it.
+
+---
+
+## 9. Preserve Before Improving
+
+Improvement can always happen later.
+
+Preservation cannot.
+
+When faced with a choice between:
+
+- perfect processing
+- complete preservation
+
+Project Thoth chooses preservation.
+
+Incomplete but preserved information is preferable to perfectly formatted information that has silently lost content.
+
+---
+
+## 10. Separation of Responsibilities
+
+Every component should have one responsibility.
+
+Capture preserves.
+
+Processors transform.
+
+Indexes organize.
+
+AI reasons.
+
+Mixing these concerns creates unnecessary complexity.
+
+---
+
+## 11. Reproducibility Matters
+
+Every generated artifact should be reproducible.
+
+A future developer should be able to regenerate:
+
+- metadata
+- manifests
+- harvests
+- search indexes
+- embeddings
+
+from the canonical archive without requiring access to the original AI platform.
+
+---
+
+## 12. Preserve Context, Not Just Content
+
+Facts without context lose meaning.
+
+Whenever possible, preserve:
+
+- ordering
+- timestamps
+- relationships
+- authorship
+- source platform
+- surrounding discussion
+
+Knowledge is more than isolated documents.
+
+It is the reasoning that connects them.
+
+---
+
+## 13. The Project Describes Itself
+
+Project Thoth repositories should be self-describing.
+
+A developer.
+
+An AI assistant.
+
+An automated process.
+
+All should be able to understand the project by reading its canonical documents.
+
+Knowledge about the project belongs inside the project.
+
+---
+
+## 14. Architecture Should Outlive Implementation
+
+Applications will be rewritten.
+
+Frameworks will change.
+
+Programming languages will evolve.
+
+The architecture should remain recognizable.
+
+Implementation serves architecture.
+
+Architecture serves philosophy.
+
+---
+
+# What Project Thoth is Not
+
+Project Thoth is not:
+
+- another note-taking application
+- another vector database
+- another chatbot
+- another RAG framework
+- another AI assistant
+
+These technologies may become components of a Project Thoth ecosystem.
+
+They are not its purpose.
+
+---
+
+# Long-Term Vision
+
+Project Thoth seeks to become a durable knowledge architecture.
+
+A place where:
+
+- conversations survive software vendors
+- ideas survive AI models
+- archives survive databases
+- knowledge survives technology shifts
+
+The objective is not simply to remember information.
+
+It is to preserve reasoning.
+
+---
+
+# Decision Filter
+
+When making architectural decisions, ask:
+
+1. Does this strengthen the archive?
+
+2. Is the result deterministic?
+
+3. Can it be regenerated?
+
+4. Does it reduce vendor dependence?
+
+5. Will this still make sense in ten years?
+
+If the answer to these questions is "yes," the decision is likely aligned with the philosophy of Project Thoth.
+
+---
+
+# Final Principle
+
+Technology changes.
+
+Knowledge endures.
+
+Project Thoth exists to ensure that the second is never held hostage by the first.

.thoth/30-glossary.md

@@ -0,0 +1,461 @@
+# Project Thoth Glossary
+
+**Version:** 1.0  
+**Status:** Canonical Terminology
+
+---
+
+# Purpose
+
+This glossary defines the canonical vocabulary used throughout Project Thoth.
+
+The purpose of this document is to ensure that humans, AI assistants, and automated tooling use the same terminology consistently.
+
+Where possible, each concept has exactly one preferred term.
+
+---
+
+# A
+
+## Archive
+
+The permanent collection of canonical source artifacts captured by Project Thoth.
+
+The archive is the authoritative source of knowledge for the project.
+
+Examples include:
+
+- conversations
+- images
+- attachments
+- audio
+- video
+
+The archive is immutable.
+
+---
+
+## Artifact
+
+Any file produced or managed by Project Thoth.
+
+Artifacts fall into two categories:
+
+- Canonical Artifacts
+- Generated Artifacts
+
+---
+
+# C
+
+## Canonical Artifact
+
+An artifact considered the permanent source of truth.
+
+Examples:
+
+- `conversation.md`
+- Original attachments
+- Images
+- Audio
+- Video
+
+Canonical artifacts are preserved indefinitely.
+
+---
+
+## Capture
+
+The act of preserving information from an external source.
+
+Capture is deterministic.
+
+Capture never interprets the information being preserved.
+
+---
+
+## Capture Connector
+
+A platform-specific adapter responsible for preserving source material.
+
+Responsibilities include:
+
+- Discovering conversations
+- Preserving formatting
+- Preserving ordering
+- Producing canonical source artifacts
+
+Capture Connectors never perform semantic analysis or AI reasoning.
+
+Examples:
+
+- ChatGPT Connector
+- Claude Connector
+- Gemini Connector
+- Open WebUI Connector
+
+---
+
+## Capture Pipeline
+
+The sequence of stages that transforms external content into canonical Project Thoth artifacts.
+
+Defined in ADR-002.
+
+```
+Discovery
+    ↓
+Intermediate Representation
+    ↓
+Transformation
+    ↓
+Serialization
+```
+
+---
+
+## Collection
+
+A logical grouping of related canonical artifacts.
+
+Collections may represent:
+
+- projects
+- research topics
+- books
+- clients
+- domains
+
+Collections organize knowledge without altering source artifacts.
+
+---
+
+## Conversation
+
+A chronological exchange between one or more participants.
+
+A conversation is preserved as a canonical artifact.
+
+---
+
+## Conversation Turn
+
+A single exchange within a conversation.
+
+A turn represents exactly one logical contribution from a participant.
+
+A turn may contain:
+
+- paragraphs
+- lists
+- tables
+- images
+- code blocks
+- attachments
+
+A turn is never divided into multiple Project Thoth messages.
+
+---
+
+# D
+
+## Derived Artifact
+
+An artifact generated from canonical source material.
+
+Derived artifacts may always be regenerated.
+
+Examples include:
+
+- metadata
+- manifests
+- harvests
+- embeddings
+- search indexes
+
+---
+
+## Discovery
+
+The process of locating logical content within an external system.
+
+Discovery is platform-specific.
+
+Discovery does not perform formatting or interpretation.
+
+---
+
+# G
+
+## Generated Artifact
+
+See **Derived Artifact**.
+
+---
+
+# H
+
+## Harvest
+
+A synthesized knowledge artifact produced from one or more canonical sources.
+
+Harvests represent interpretation rather than preservation.
+
+Harvests are always generated.
+
+---
+
+# I
+
+## Intermediate Representation (IR)
+
+The platform-neutral model produced after discovery.
+
+The IR separates platform-specific extraction from platform-independent processing.
+
+The IR is not normally stored permanently.
+
+---
+
+# K
+
+## Knowledge Repository
+
+The organized collection of canonical and generated artifacts managed by Project Thoth.
+
+The repository represents the project's complete preserved knowledge.
+
+---
+
+# M
+
+## Manifest
+
+A generated document describing a collection of artifacts.
+
+A manifest typically records:
+
+- included files
+- relationships
+- metadata
+- processing status
+
+Manifests are generated and may be regenerated at any time.
+
+---
+
+## Markdown
+
+The canonical document format used by Project Thoth.
+
+Markdown is preferred because it is:
+
+- human-readable
+- portable
+- version-control friendly
+- widely supported
+
+---
+
+## Metadata
+
+Structured information describing an artifact.
+
+Examples include:
+
+- title
+- author
+- capture date
+- source platform
+- tags
+- relationships
+
+Metadata is generated from canonical artifacts.
+
+---
+
+# P
+
+## Philosophy
+
+The enduring principles that guide architectural decisions.
+
+The philosophy explains *why* Project Thoth is designed the way it is.
+
+---
+
+## Processor
+
+A platform-independent component that transforms canonical artifacts into generated artifacts.
+
+Examples include:
+
+- Metadata Generator
+- Manifest Generator
+- Harvest Generator
+
+Processors never modify canonical artifacts.
+
+---
+
+## Project Self-Description
+
+The collection of documents contained within the `.thoth` directory.
+
+These documents allow humans and AI systems to understand the project without relying on external knowledge.
+
+---
+
+# R
+
+## Repository
+
+The complete Project Thoth project, including:
+
+- applications
+- archive
+- processors
+- documentation
+- specifications
+- work orders
+- canonical project description
+
+---
+
+# S
+
+## Serialization
+
+The process of writing transformed content into a canonical Project Thoth document.
+
+Examples include:
+
+- `conversation.md`
+- metadata files
+- manifests
+
+---
+
+## Source Artifact
+
+A canonical artifact captured directly from an external source.
+
+Source artifacts are never regenerated.
+
+---
+
+## Source Platform
+
+The external system from which information was captured.
+
+Examples:
+
+- ChatGPT
+- Claude
+- Gemini
+- Microsoft Copilot
+- Open WebUI
+
+---
+
+## Specification
+
+A document defining the canonical structure of Project Thoth artifacts.
+
+Specifications describe formats rather than implementations.
+
+---
+
+# T
+
+## Transformation
+
+The process of converting source content into canonical Project Thoth formats.
+
+Examples include:
+
+- HTML → Markdown
+- DOM → Intermediate Representation
+
+Transformation does not alter meaning.
+
+---
+
+## Turn Renderer
+
+A component responsible for converting one Conversation Turn into canonical Markdown.
+
+A Turn Renderer never discovers conversation turns.
+
+---
+
+# V
+
+## Vault
+
+A user-managed knowledge repository containing canonical Project Thoth artifacts.
+
+The vault is tool-independent.
+
+Applications such as Obsidian, VS Code, or future tools may operate on the same vault.
+
+The vault is not defined by any particular application.
+
+---
+
+# W
+
+## Work Order
+
+A structured engineering document describing a discrete unit of implementation work.
+
+A Work Order contains:
+
+- context
+- objectives
+- constraints
+- acceptance criteria
+- architectural guidance
+
+Work Orders are intended to be executable by either human developers or AI assistants.
+
+Work Orders are stored under the `codex/` directory.
+
+---
+
+# Canonical Terminology
+
+The following preferred terms should be used consistently throughout Project Thoth.
+
+| Preferred | Avoid |
+|-----------|-------|
+| Archive | Database (when referring to preserved knowledge) |
+| Capture Connector | Scraper |
+| Conversation Turn | Message Block |
+| Derived Artifact | Output File |
+| Discovery | DOM Parsing |
+| Intermediate Representation | Temporary Object |
+| Markdown Serialization | Export |
+| Processor | Script |
+| Source Artifact | Raw File |
+| Vault | Obsidian Vault |
+
+---
+
+# Naming Principles
+
+When introducing new terminology:
+
+1. Prefer nouns over verbs.
+2. Use one canonical term for each concept.
+3. Avoid vendor-specific language.
+4. Prefer platform-neutral terminology.
+5. Preserve consistency over novelty.
+
+---
+
+# Final Principle
+
+A shared vocabulary is part of the project's architecture.
+
+When every contributor—human or AI—uses the same words to describe the same concepts, communication becomes more precise, architectural decisions become easier to understand, and knowledge becomes more durable.

.thoth/40-coding-standards.md

@@ -0,0 +1,429 @@
+# Project Thoth Coding Standards
+
+**Version:** 1.0  
+**Status:** Canonical Development Standard
+
+---
+
+# Purpose
+
+This document defines the engineering standards used throughout Project Thoth.
+
+The objective is not merely to produce working software, but to produce software that remains understandable, maintainable, and portable over time.
+
+These standards apply equally to:
+
+- Human developers
+- AI-assisted development
+- Autonomous development agents
+
+When implementation choices conflict with these standards, architectural decisions (ADRs) take precedence.
+
+---
+
+# Core Principles
+
+## 1. Architecture Before Code
+
+Every significant implementation should begin with architecture.
+
+If a design decision is expected to persist beyond a single implementation, document it in an Architecture Decision Record (ADR) before coding.
+
+Code should implement architecture—not define it.
+
+---
+
+## 2. Prefer Refactoring Over Patching
+
+When repeated fixes indicate a flawed design, refactor rather than accumulate patches.
+
+Signs that refactoring is warranted include:
+
+- duplicate logic
+- increasing conditional complexity
+- repeated bug fixes in the same area
+- unclear module responsibilities
+- growing technical debt
+
+The goal is long-term simplicity, not short-term completion.
+
+---
+
+## 3. Single Responsibility
+
+Every module should have one clear responsibility.
+
+Examples:
+
+Good:
+
+- Conversation Discovery
+- HTML-to-Markdown Conversion
+- Markdown Serialization
+- Metadata Generation
+
+Poor:
+
+- ExtractConversationAndGenerateMarkdownAndDownload()
+
+If a component's name requires multiple conjunctions ("and", "or"), it likely has more than one responsibility.
+
+---
+
+## 4. Separation of Concerns
+
+Capture, transformation, processing, and presentation are independent concerns.
+
+Each should exist in its own layer.
+
+No layer should assume the responsibilities of another.
+
+---
+
+## 5. Deterministic Behavior
+
+Given the same input, Project Thoth components should produce the same output.
+
+Randomness, hidden state, and side effects should be avoided unless explicitly required.
+
+---
+
+# Repository Organization
+
+The repository should separate concerns by purpose rather than technology.
+
+Typical structure:
+
+```text
+.thoth/
+applications/
+archive/
+codex/
+docs/
+processors/
+specifications/
+```
+
+Each top-level directory should represent a distinct architectural concern.
+
+---
+
+# Module Design
+
+Modules should be:
+
+- cohesive
+- loosely coupled
+- independently testable
+
+Modules should expose small, well-defined interfaces.
+
+Avoid exposing internal implementation details.
+
+---
+
+# Function Design
+
+Functions should:
+
+- perform one task
+- have descriptive names
+- avoid unnecessary side effects
+- return predictable results
+
+Prefer composition over deeply nested logic.
+
+---
+
+# Error Handling
+
+Errors should be:
+
+- explicit
+- actionable
+- recoverable when practical
+
+Never silently discard data.
+
+When partial processing is possible:
+
+- preserve available information
+- report the failure
+- continue processing where safe
+
+Preservation takes precedence over perfection.
+
+---
+
+# Logging
+
+Logs should assist debugging without becoming part of the application's behavior.
+
+Log messages should answer:
+
+- What happened?
+- Why did it happen?
+- What should the developer investigate next?
+
+Avoid excessive or repetitive logging.
+
+---
+
+# Documentation
+
+Document architecture rather than implementation details.
+
+Prefer:
+
+- ADRs
+- specifications
+- interfaces
+- module responsibilities
+
+Avoid comments that merely repeat what the code already expresses.
+
+Comments should explain *why*, not *what*.
+
+---
+
+# Naming
+
+Choose names that reflect business concepts rather than implementation details.
+
+Prefer:
+
+- ConversationTurn
+- CaptureConnector
+- ManifestGenerator
+
+Avoid:
+
+- TempData
+- Helper
+- Utils
+- Stuff
+
+Names should communicate intent.
+
+---
+
+# Interfaces
+
+Define interfaces at architectural boundaries.
+
+Examples include:
+
+- Capture Connector
+- Processor
+- Serializer
+
+Interfaces should remain stable even when implementations change.
+
+---
+
+# Dependencies
+
+Minimize external dependencies.
+
+Before adding a dependency, ask:
+
+- Does the standard library already solve this?
+- Does this dependency simplify architecture?
+- Is it actively maintained?
+- Can the dependency be removed later without significant effort?
+
+Favor long-lived, well-supported libraries.
+
+---
+
+# File Formats
+
+Project Thoth prefers open formats.
+
+Preferred formats include:
+
+- Markdown
+- YAML
+- JSON
+- Plain text
+
+Avoid introducing proprietary formats unless there is a compelling architectural reason.
+
+---
+
+# Testing
+
+Testing should occur at multiple levels.
+
+Examples:
+
+- Unit tests
+- Integration tests
+- End-to-end workflow tests
+
+Where practical, preserve representative fixtures for regression testing.
+
+Regression tests are especially important for parsers and capture connectors.
+
+---
+
+# AI-Assisted Development
+
+AI is a development assistant, not an architectural authority.
+
+AI-generated code should be reviewed for:
+
+- correctness
+- simplicity
+- architectural alignment
+- maintainability
+
+AI should implement established architecture rather than invent new architecture during implementation.
+
+---
+
+# Work Orders
+
+Implementation work should be described using Work Orders.
+
+A Work Order should include:
+
+- context
+- objective
+- constraints
+- deliverables
+- acceptance criteria
+- architectural references
+
+Work Orders should be executable with minimal additional explanation.
+
+---
+
+# Refactoring
+
+Refactoring should preserve observable behavior while improving internal structure.
+
+Typical reasons include:
+
+- simplifying design
+- improving readability
+- reducing duplication
+- improving testability
+- aligning implementation with updated architecture
+
+Refactoring should not introduce unrelated feature work.
+
+---
+
+# Code Reviews
+
+Reviews should evaluate:
+
+1. Architectural alignment
+2. Correctness
+3. Readability
+4. Maintainability
+5. Simplicity
+
+The primary question is not:
+
+> "Does it work?"
+
+Instead ask:
+
+> "Will another developer understand this in two years?"
+
+---
+
+# Performance
+
+Optimize for clarity first.
+
+Optimize for performance when:
+
+- measurement identifies a bottleneck
+- scalability requires it
+- architectural goals demand it
+
+Avoid premature optimization.
+
+---
+
+# Security
+
+Treat external input as untrusted.
+
+Validate:
+
+- user input
+- downloaded content
+- file paths
+- URLs
+- serialized data
+
+Avoid embedding secrets in source code or repositories.
+
+---
+
+# Backward Compatibility
+
+When changing canonical formats:
+
+- preserve compatibility where practical
+- document breaking changes
+- update specifications
+- record architectural decisions in ADRs
+
+---
+
+# Technical Debt
+
+Technical debt should be visible.
+
+Known debt should be documented rather than ignored.
+
+Temporary solutions should include:
+
+- rationale
+- limitations
+- expected future resolution
+
+---
+
+# Definition of Done
+
+Work is considered complete when:
+
+- implementation satisfies the Work Order
+- acceptance criteria are met
+- architecture remains consistent
+- documentation is updated if required
+- tests pass (where applicable)
+- no known regressions have been introduced
+
+Completion is measured by quality, not by the number of lines of code written.
+
+---
+
+# Coding Philosophy
+
+Project Thoth values software that is:
+
+- understandable
+- deterministic
+- modular
+- portable
+- maintainable
+- testable
+
+The objective is to create software that remains useful long after the original implementation has evolved.
+
+---
+
+# Final Principle
+
+Good software preserves knowledge.
+
+Great software preserves understanding.
+
+Every design decision, module, and line of code should make the project easier for the next developer—or the next AI assistant—to understand.

.thoth/50-roadmap.md

@@ -0,0 +1,419 @@
+# Project Thoth Roadmap
+
+**Version:** 1.0  
+**Status:** Living Document
+
+---
+
+# Purpose
+
+This roadmap describes the long-term evolution of Project Thoth.
+
+Unlike `00-project-state.md`, which describes the project's current implementation, this document describes the intended direction of the platform.
+
+The roadmap is intentionally high-level.
+
+Implementation details belong in Work Orders, ADRs, and project-specific documentation.
+
+---
+
+# Vision
+
+Project Thoth will become a platform for preserving, organizing, processing, and retrieving human knowledge independent of any AI provider or software vendor.
+
+Its primary objective is to create a durable knowledge architecture where information can be captured once and continuously reprocessed as technology evolves.
+
+---
+
+# Guiding Principles
+
+The roadmap follows several principles:
+
+- Build vertically before horizontally.
+- Preserve before processing.
+- Prefer deterministic systems.
+- Keep platform-specific code isolated.
+- Favor reusable processors over application-specific logic.
+- Introduce AI only after preservation is complete.
+
+---
+
+# Phase 1 — Foundation
+
+## Objective
+
+Establish the architectural and technical foundations of Project Thoth.
+
+### Deliverables
+
+- Reference Architecture
+- Project structure
+- ADR framework
+- Repository standards
+- Canonical specifications
+- `.thoth` project self-description
+- Initial Work Order framework
+
+### Success Criteria
+
+Project architecture is stable and documented.
+
+---
+
+# Phase 2 — Capture MVP
+
+## Objective
+
+Capture conversations from ChatGPT into canonical Project Thoth artifacts.
+
+### Deliverables
+
+- Browser extension
+- ChatGPT connector
+- Conversation discovery
+- DOM-to-Markdown transformation
+- Markdown serialization
+- Download support
+- Basic user feedback
+
+### Success Criteria
+
+Conversations can be captured with high fidelity into `conversation.md`.
+
+---
+
+# Phase 3 — Capture Framework
+
+## Objective
+
+Generalize the ChatGPT implementation into a reusable connector framework.
+
+### Deliverables
+
+- Capture Connector interface
+- Canonical Conversation Model
+- Shared HTML-to-Markdown engine
+- Shared Markdown serializer
+- Connector testing framework
+
+### Target Connectors
+
+- ChatGPT
+- Claude
+- Gemini
+- Microsoft Copilot
+- Open WebUI
+
+### Success Criteria
+
+New connectors primarily require implementation of platform-specific discovery.
+
+---
+
+# Phase 4 — Processor Framework
+
+## Objective
+
+Build reusable processors that operate on canonical source artifacts.
+
+### Initial Processors
+
+- Metadata Generator
+- Manifest Generator
+- Harvest Generator
+
+### Future Processors
+
+- Relationship extraction
+- Citation generation
+- Cross-reference generation
+- Knowledge graph generation
+
+### Success Criteria
+
+Processors are independent of capture connectors.
+
+---
+
+# Phase 5 — Archive Management
+
+## Objective
+
+Create a durable archive for canonical artifacts.
+
+### Features
+
+- Archive organization
+- Collection management
+- Version tracking
+- Attachment management
+- Integrity validation
+
+### Success Criteria
+
+The archive becomes the canonical source of knowledge.
+
+---
+
+# Phase 6 — Knowledge Repository
+
+## Objective
+
+Organize captured knowledge into a coherent repository.
+
+### Features
+
+- Cross-linking
+- Collections
+- Relationships
+- Metadata indexing
+- Search preparation
+
+### Success Criteria
+
+Knowledge can be navigated independently of its original source platform.
+
+---
+
+# Phase 7 — Search
+
+## Objective
+
+Provide deterministic search across the repository.
+
+### Features
+
+- Full-text search
+- Metadata search
+- Collection search
+- Relationship search
+- Citation search
+
+### Success Criteria
+
+Users can reliably locate preserved knowledge without AI assistance.
+
+---
+
+# Phase 8 — AI Integration
+
+## Objective
+
+Enable AI systems to consume the repository.
+
+### Features
+
+- Local LLM integration
+- Context packaging
+- Prompt generation
+- Retrieval interfaces
+- Knowledge injection
+
+### Target Platforms
+
+- Ollama
+- Open WebUI
+- ChatGPT
+- Claude
+- Gemini
+
+### Success Criteria
+
+AI systems become consumers of the archive rather than owners of knowledge.
+
+---
+
+# Phase 9 — Knowledge Operations
+
+## Objective
+
+Support organizational knowledge management.
+
+### Features
+
+- Team repositories
+- Shared collections
+- Governance
+- Retention policies
+- Workflow automation
+- Knowledge health metrics
+
+### Success Criteria
+
+Organizations can manage institutional knowledge using Project Thoth.
+
+---
+
+# Phase 10 — Project Thoth Platform
+
+## Objective
+
+Transform Project Thoth into a complete knowledge platform.
+
+### Features
+
+- Native applications
+- Plugin architecture
+- Processor marketplace
+- Connector marketplace
+- Automation framework
+- Scheduled processing
+- Background services
+
+### Success Criteria
+
+Project Thoth becomes an extensible ecosystem.
+
+---
+
+# Parallel Work Streams
+
+Several work streams evolve throughout the roadmap.
+
+---
+
+## Capture Connectors
+
+Examples include:
+
+- ChatGPT
+- Claude
+- Gemini
+- Microsoft Copilot
+- Open WebUI
+- Cursor
+- GitHub Copilot Chat
+- Future AI platforms
+
+---
+
+## Processors
+
+Examples include:
+
+- Metadata
+- Manifest
+- Harvest
+- Summaries
+- Search indexing
+- Embeddings
+- Relationship analysis
+
+---
+
+## Specifications
+
+Examples include:
+
+- Conversation Specification
+- Metadata Specification
+- Manifest Specification
+- Harvest Specification
+- Package Specification
+
+---
+
+## Applications
+
+Potential applications include:
+
+- Browser Capture
+- Desktop Archive Manager
+- Knowledge Explorer
+- Search Portal
+- Processor Runner
+- Administration Console
+
+---
+
+# Future Capabilities
+
+Potential future capabilities include:
+
+- Automatic conversation synchronization
+- Email capture
+- Document ingestion
+- PDF processing
+- Audio transcription
+- Video indexing
+- OCR
+- Knowledge graph visualization
+- Timeline reconstruction
+- Citation management
+- Research workspaces
+- Multi-user collaboration
+
+These features are intentionally deferred until the core preservation architecture is mature.
+
+---
+
+# Non-Goals
+
+Project Thoth is not intended to become:
+
+- another chatbot
+- another note-taking application
+- another vector database
+- another proprietary knowledge silo
+
+These technologies may be integrated where appropriate, but they are not the project's primary purpose.
+
+---
+
+# Milestone Philosophy
+
+Each milestone should deliver independently valuable functionality.
+
+The project should remain useful even if later phases are never completed.
+
+Earlier phases should minimize assumptions about later implementation choices.
+
+---
+
+# Success Measures
+
+Progress should be measured by:
+
+- Preservation fidelity
+- Architectural stability
+- Deterministic processing
+- Platform independence
+- Ease of extension
+- Long-term maintainability
+
+Feature count is not a primary measure of success.
+
+---
+
+# Living Roadmap
+
+This roadmap is expected to evolve.
+
+New phases may be added.
+
+Existing phases may be reordered.
+
+However, changes should preserve the project's guiding philosophy:
+
+1. Capture.
+2. Preserve.
+3. Process.
+4. Organize.
+5. Retrieve.
+6. Reason.
+
+Reasoning is the final stage—not the first.
+
+---
+
+# Final Vision
+
+Project Thoth is not simply a collection of tools.
+
+It is an architecture for preserving human reasoning.
+
+The long-term goal is to ensure that knowledge remains accessible, portable, and understandable regardless of which AI systems, software platforms, or technologies come and go.
+
+Technology will continue to evolve.
+
+The archive should not have to.