State-hub connect and initial workplans

SCOPE.md

@@ -0,0 +1,147 @@
+# 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 Repositories
+
+- `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]
+```
+