# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Intelligent markdown engine and information management platform — treats documents as structured, queryable information spaces with schema validation, transclusion, LLM-driven evaluation, and infospace lifecycle management.

---

## Core Idea

MarkiTect turns fragmented knowledge (scattered docs, chats, notes) into structured, versioned, reusable artifacts. The core abstraction is an **infospace**: a curated collection of typed entities (concepts, mechanisms, observations) governed by a YAML config, validated against schemas, and evaluated for quality across five dimensions. The platform automates generation, validation, and transformation at scale, delegating domain-level judgment to LLMs while Python handles structure and evaluation.

---

## In Scope

- Parse, validate, and analyze markdown documents against schemas
- Generate schemas from example documents; enforce naming convention `{domain}-schema-v{major}.{minor}.md`
- Infospace lifecycle: create, populate, evaluate (per-entity + collection quality scores), compose, export
- Transclusion: embed content from one document into another, maintaining single source of truth
- LLM-driven prompt execution with dependency resolution and quality gates
- Relationship graph export (Mermaid, DOT) and analysis (networkx, FCA)
- Batch document processing; CLI (`markitect <command>`) and programmatic API
- Rendering: markdown → interactive HTML via plugin system (testdrive-jsui)
- Asset management (image embedding, resource handling)

---

## Out of Scope

- Visual/WYSIWYG editing (markdown-first, text-based workflows only)
- Real-time collaborative editing (git-based versioning instead)
- Financial transactions or external payment integration
- Making domain-level judgments in Python code (delegated to LLM via prompt templates)
- Storing secrets or credentials in plaintext
- Full GraphQL API (structure exists but not fully implemented)
- Vendor-specific integrations or lock-in

---

## Relevant When

- Managing large document sets (hundreds to thousands) needing consistent structure and validation
- Building or maintaining institutional knowledge bases, technical documentation, or canon releases
- Automating document generation from schemas or templates
- Tracking relationships and dependencies between knowledge artifacts
- Needing programmatic access to document structure (beyond file reading)
- Applying quality evaluation to a structured concept collection

---

## Not Relevant When

- Working with a handful of simple, unrelated documents
- Visual editor required
- Exclusively non-markdown source formats (PDF/Word need conversion first)
- No consistency, validation, or automation needed

---

## Current State

- Status: active (v0.13.0-dev, ~90 commits ahead of release)
- Implementation: substantial — core modules mature (CLI, parsing, schema management, prompt execution, infospace); infospace S3 close-out in progress; LLM adapter extracted to standalone `llm-connect` package
- Stability: stable core; plugin system and infospace tooling evolving; 200+ CHANGELOG entries since v0.6.0
- Usage: active personal development; examples with 988 entities and full evaluation pipeline

---

## How It Fits

- Upstream dependencies: `llm-connect` (LLM adapter library, extracted), `testdrive-jsui` (rendering plugin submodule), `markitect-utils` (utility library)
- Downstream consumers: Custodian — MarkiTect is the knowledge artifact platform in the canonical dependency order (Railiance → **Markitect** → Coulomb.social → Personhood/Foerster → Custodian)
- Often used with: the-custodian (state hub tracks markitect domain workstreams), kaizen-agentic (project-management agent for session workflow)

---

## Terminology

- Preferred terms: infospace, topic, discipline, entity, evaluation, viability, transclusion, schema, quality gates
- Also known as: "markitect", "the markdown engine"
- Potentially confusing terms: "topic" = the subject matter an infospace explains (not a chat thread); "discipline" = a reusable framework of concepts (itself a viable infospace); "infospace" ≠ filesystem directory (it's a curated conceptual collection with explicit quality thresholds)

---

## Related / Overlapping

- `llm-connect` — standalone LLM adapter extracted from MarkiTect (dependency)
- `the-custodian` — tracks markitect workstreams; custodian canon includes a markitect domain charter
- `marki-docx` — separate repo (on tegwick machine); relationship: docx export capability for MarkiTect artifacts

---

## Provided Capabilities

```capability
type: documentation
title: Structured document validation and schema management
description: Parse, validate, and enforce schemas on markdown documents — generate schemas from examples, validate entity collections, report naming convention compliance.
keywords: [markdown, schema, validation, document, structure, linting]
```

```capability
type: documentation
title: Infospace lifecycle management
description: Create, populate, evaluate (quality scores), compose, and export curated knowledge collections (infospaces) with transclusion and relationship graph analysis.
keywords: [infospace, knowledge, curation, evaluation, transclusion, quality, graph]
```

```capability
type: data
title: LLM-driven knowledge artifact generation
description: Execute prompts with dependency resolution and quality gates to generate typed entities — concepts, mechanisms, observations — at scale from schemas and templates.
keywords: [llm, generation, prompt, entity, artifact, knowledge, automation]
```

---

## Getting Oriented

- Start with: `CLAUDE.md` (dev commands, LLM config, infospace lifecycle), `INTRODUCTION.md` (use cases, philosophy)
- Key files / directories: `markitect/cli.py` (CLI entry point), `markitect/infospace/` (primary active area), `markitect/prompts/` (LLM execution), `roadmap/` (6 active planning tracks), `examples/infospace-with-history/` (988-entity reference implementation)
- Entry points: `markitect --help`; `markitect infospace --help`; `pytest tests/unit/` (inner TDD loop)
