generated from coulomb/repo-seed
147 lines
5.0 KiB
Markdown
147 lines
5.0 KiB
Markdown
# 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
|
|
|
|
AI-first, headless knowledge engine that makes structured knowledge persistent,
|
|
queryable, orchestratable, and operable across formats.
|
|
|
|
---
|
|
|
|
## Core Idea
|
|
|
|
`kontextual-engine` is the system-layer successor to the platform portions of
|
|
`markitect-main`. It should preserve the useful ideas around infospaces,
|
|
knowledge artifacts, relationships, retrieval, workflow execution, and agent
|
|
context, while avoiding the old repo's mixed ownership of markdown primitives,
|
|
UI, provider integrations, and project/domain content.
|
|
|
|
The engine owns the runtime contract for persistent knowledge systems. Lower
|
|
level syntax operations belong in `markitect-tool`; concrete domain workspaces
|
|
belong in `infospace-bench`.
|
|
|
|
---
|
|
|
|
## In Scope
|
|
|
|
- Persistent storage and lifecycle management for knowledge artifacts.
|
|
- Collections/domains, metadata, and relationships between artifacts.
|
|
- Multi-format ingestion interfaces and normalized internal representations.
|
|
- Query, retrieval, indexing, and composition APIs.
|
|
- Workflow orchestration for transformation, generation, and analysis.
|
|
- Agent-facing context continuity and operation surfaces.
|
|
- Integration adapters for lower-layer tools such as `markitect-tool`.
|
|
- Structured errors, deterministic behavior where applicable, and auditable
|
|
state transitions.
|
|
|
|
---
|
|
|
|
## Out of Scope
|
|
|
|
- Low-level markdown parsing, schema primitives, document transforms, or CLI
|
|
tooling that belongs in `markitect-tool`.
|
|
- Visual UI applications, rendering plugins, or WYSIWYG editing.
|
|
- Domain-specific infospace content or benchmark corpora that belong in
|
|
`infospace-bench`.
|
|
- Direct ownership of LLM provider adapters; use `llm-connect` or equivalent.
|
|
- Finance, issue tracking, profile management, release tooling, and other
|
|
legacy `markitect-main` utilities unrelated to the engine contract.
|
|
- A CLI-first product posture; any CLI should remain an administrative or
|
|
development convenience over service/programmatic APIs.
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- A project needs durable knowledge artifacts instead of one-off file parsing.
|
|
- Agents need stable context and retrievable state across sessions.
|
|
- Workflows must ingest, normalize, transform, compose, and query knowledge.
|
|
- Multiple formats and external tooling need a common runtime layer.
|
|
- A higher-level application needs a headless knowledge service.
|
|
|
|
---
|
|
|
|
## Not Relevant When
|
|
|
|
- The task is only markdown syntax manipulation or schema validation.
|
|
- The primary need is an end-user visual application.
|
|
- The work is domain-specific corpus curation without runtime needs.
|
|
- Provider-specific LLM client behavior is the main concern.
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
- Status: scoping / foundation.
|
|
- Implementation: documentation and workplans only.
|
|
- Stability: evolving.
|
|
- Usage: successor planning for the in-scope system-layer parts of
|
|
`markitect-main`.
|
|
|
|
---
|
|
|
|
## How It Fits
|
|
|
|
- Upstream dependencies: `markitect-tool` for syntax-layer primitives,
|
|
`llm-connect` for provider-neutral LLM access, storage backends to be chosen.
|
|
- Downstream consumers: `infospace-bench`, future knowledge services, agents,
|
|
and automation systems.
|
|
- Often used with: State Hub for planning/coordination, markitect ecosystem
|
|
repos for adjacent responsibilities.
|
|
|
|
---
|
|
|
|
## Terminology
|
|
|
|
- Preferred terms: knowledge artifact, collection, relationship, ingestion,
|
|
normalization, workflow, context, operation.
|
|
- Also known as: Kontextual Engine, knowledge runtime, headless knowledge
|
|
engine.
|
|
- Potentially confusing terms: "infospace" is a conceptual collection pattern
|
|
inherited from `markitect-main`, not necessarily a project directory or a
|
|
UI-facing workspace.
|
|
|
|
---
|
|
|
|
## Related / Overlapping
|
|
|
|
- `markitect-main` — legacy mixed platform; source for candidate behavior and
|
|
tests, not the target architecture.
|
|
- `markitect-tool` — syntax layer for markdown and structured document
|
|
primitives.
|
|
- `infospace-bench` — application/project layer for concrete knowledge spaces.
|
|
- `llm-connect` — LLM provider abstraction that this repo may call but should
|
|
not replace.
|
|
- `the-custodian/state-hub` — coordination and repo/workplan index.
|
|
|
|
---
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: `INTENT.md`, `wiki/ProductRequirementsDocument.md`,
|
|
`wiki/FunctionalRequirementsSpecification.md`.
|
|
- Key files / directories: `docs/`, `workplans/`, `SCOPE.md`, `CLAUDE.md`.
|
|
- Entry points: none yet; implementation starts from the workplans.
|
|
|
|
---
|
|
|
|
## Provided Capabilities
|
|
|
|
```capability
|
|
type: service
|
|
title: Persistent knowledge runtime
|
|
description: Provides the planned system layer for storing, querying, transforming, and orchestrating structured knowledge artifacts across formats.
|
|
keywords: [knowledge, runtime, persistence, orchestration, retrieval]
|
|
```
|
|
|
|
```capability
|
|
type: automation
|
|
title: Agent-operable knowledge workflows
|
|
description: Provides planned APIs and workflow surfaces that let agents access context, trigger transformations, and operate over durable knowledge state.
|
|
keywords: [agent, workflow, context, automation, knowledge]
|
|
```
|