# SCOPE

> This file helps agents and humans quickly understand what this repository is
> about, when it is relevant, and when it is not.

---

## One-Liner

Headless knowledge operations engine for turning heterogeneous information
assets into persistent, contextual, governed, retrievable, transformable, and
agent-operable knowledge.

---

## Core Idea

`kontextual-engine` provides reusable backend capabilities for making fragmented
information operational. It is meant to sit behind applications, automation,
workflows, services, and AI agents that need durable knowledge assets rather
than disconnected files, documents, records, notes, datasets, generated outputs,
or content collections.

The engine owns stable asset identity, source provenance, metadata,
relationships, lifecycle state, permission-aware retrieval, traceable
transformation, workflow state, auditability, exportability, and controlled
agent operation.

It should support CMS-like, DMS-like, ECM-like, file-service, knowledge-base,
research-support, and AI-assisted workflow use cases without becoming a finished
end-user application in any one category.

---

## In Scope

- Knowledge asset registry with stable asset IDs.
- Persistent management of source, normalized, and derived asset forms.
- Source references, provenance, ingestion history, and lifecycle state.
- Multi-format ingestion and normalization for common knowledge assets.
- Metadata, classification, custom schemas, contextual entities, and typed
  relationships.
- Search, filtering, querying, source-grounded snippets, relationship retrieval,
  and permission-aware access.
- Traceable transformations that produce derived artifacts with lineage.
- Workflow and job orchestration for ingestion, enrichment, validation, review,
  transformation, publication, archival, synchronization, and export.
- Actors, permissions, policy checks, review gates, audit logs, and
  fail-closed operation for ambiguous access.
- Agent-safe operation through explicit, bounded, permissioned, auditable, and
  reviewable APIs.
- Service and programmatic APIs, adapter boundaries, extension hooks, events,
  observability, export, and portability.

---

## Out of Scope

- A finished end-user ECM, DMS, CMS, intranet, workspace, or file-sharing
  product by itself.
- A visual website builder, WYSIWYG authoring suite, or document editor.
- A file sync client or simple file browser.
- A markdown-specific tooling layer; low-level markdown operations belong in
  `markitect-tool` or equivalent adapters.
- A pure vector database, standalone search appliance, or generic chatbot over
  documents.
- A domain-specific knowledge base with hard-coded legal, support, research, or
  marketing semantics.
- Direct ownership of every enterprise connector, AI provider, embedding model,
  search backend, workflow engine, or deployment platform.
- Direct ownership of LLM provider adapters; use `llm-connect` or equivalent
  provider-neutral integrations.

---

## Relevant When

- A project needs stable knowledge asset identity rather than path-only file
  references.
- Heterogeneous documents, files, markdown, PDFs, datasets, notes, records, or
  generated outputs need a common operational layer.
- Search, retrieval, transformations, workflows, and AI operations must preserve
  provenance, permissions, and auditability.
- Derived summaries, reports, extracts, classifications, or generated artifacts
  must remain traceable to source assets and operation context.
- AI agents need bounded, permissioned, source-grounded context and explicit
  operation surfaces.
- A higher-level product needs a headless knowledge engine rather than another
  monolithic content application.

---

## Not Relevant When

- The task is only low-level markdown syntax manipulation or schema validation.
- The primary need is a polished end-user UI.
- The desired product is a file synchronization client or office editor.
- A project only needs a vector index without durable identity, provenance,
  permissions, workflows, audit, or derived artifact lineage.
- The work is domain-specific corpus curation without reusable engine needs.

---

## Current State

- Status: foundation complete; roadmap re-scoped around the V0.2 knowledge
  operations vision.
- Implementation: first runtime slice exists for artifacts, collections,
  relationships, in-memory storage, ingestion adapters, query, workflow run
  manifests, and agent-facing context packages.
- Next work: execute `KONT-WP-0004` through `KONT-WP-0010`, starting with the
  architecture rebase and then building durable governed asset operations.

---

## Keywords

knowledge, content, assets, provenance, retrieval, governance, audit,
workflow, transformation, agent-safe, API-first, metadata, relationships,
ingestion, export, portability