# kontextual-engine Agent Guide

This repository is tracked in the Custodian State Hub as:

- Domain: `markitect`
- Repo slug: `kontextual-engine`
- Topic ID: `5571d954-0d30-4950-980d-7bcaaad8e3e2`
- Workplan prefix: `KONT-WP`

At session start, orient from:

1. `.custodian-brief.md`
2. `INTENT.md`
3. `wiki/ProductRequirementsDocument.md`
4. `wiki/FunctionalRequirementsSpecification.md`
5. `docs/stack-decision.md`
6. `docs/markitect-main-scope-assessment.md`
7. Active files in `workplans/`

## State Hub

This repo is registered with State Hub through the local Custodian service.
State Hub is an index/cache for coordination state; authoritative work items
live in this repository as Markdown workplans.

Local API:

```bash
curl -s http://127.0.0.1:8000/state/health
curl -s http://127.0.0.1:8000/repos/kontextual-engine | python3 -m json.tool
```

At session close, record notable progress:

```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
  -H "Content-Type: application/json" \
  -d '{"summary":"what changed","event_type":"note","author":"codex"}'
```

After workplan file changes, ask the custodian operator to run from
`/home/worsch/the-custodian/state-hub`:

```bash
make fix-consistency REPO=kontextual-engine
```

## Boundary

`kontextual-engine` is the system-layer successor to the runtime/platform parts
of `markitect-main`.

It owns:

- Persistent knowledge artifacts and collections.
- Artifact metadata and relationships.
- Ingestion and normalization interfaces.
- Query, retrieval, and composition service contracts.
- Workflow orchestration and operation tracking.
- Agent-operable context and action surfaces.
- Integration boundaries to `markitect-tool` and `llm-connect`.

It does not own:

- Markdown syntax primitives or document-level schema tooling.
- End-user visual UI applications or rendering plugins.
- Domain-specific knowledge content.
- Provider-specific LLM adapters.
- Legacy finance, issue, profile, release, or project-management utilities.

## Development Posture

Prefer clean reimplementation around the new PRD/FRS. Use `markitect-main` as
reference material for behavior, tests, and domain vocabulary, not as an
architecture to copy wholesale.

## Stack And Commands

- Python target: 3.12+
- Distribution: `kontextual-engine`
- Import package: `kontextual_engine`
- Build backend: `setuptools`
- Test runner: `pytest`
- Source layout: `src/kontextual_engine`
- Service framework: FastAPI as an optional boundary after the programmatic API
  stabilizes

Run tests:

```bash
python3 -m pytest
```

## Workplans

Workplans live in `workplans/` and follow the Custodian ADR-001 convention:

- Frontmatter declares `type: workplan`, `domain: markitect`, `repo:
  kontextual-engine`, and `owner: codex`.
- Tasks are embedded as headed sections with fenced `task` blocks.
- State Hub may index these files, but the files remain authoritative.