Finish repository foundation workplan

docs/stack-decision.md

@@ -0,0 +1,50 @@
+# Stack Decision
+
+Date: 2026-05-05
+
+## Decision
+
+`kontextual-engine` starts as a Python 3.12+ package with:
+
+- Distribution name: `kontextual-engine`
+- Import package: `kontextual_engine`
+- Build backend: `setuptools`
+- Test runner: `pytest`
+- Source layout: `src/kontextual_engine`
+- First service framework: FastAPI, added as an optional `service` extra
+
+The first implementation should stabilize the programmatic API before exposing
+HTTP endpoints. The service layer should wrap the same contracts rather than
+becoming the architecture driver.
+
+## Initial Dependencies
+
+Core dependencies:
+
+- `pydantic>=2.0` for explicit runtime models and validation.
+
+Optional extras:
+
+- `dev`: `pytest`
+- `service`: `fastapi`, `uvicorn`
+- `storage`: `sqlalchemy`
+- `markdown`: local `markitect-tool` adapter dependency
+- `llm`: local `llm-connect` adapter dependency
+
+## Rationale
+
+The PRD/FRS describe a headless runtime, not a CLI-first tool. Python keeps the
+repo aligned with `markitect-tool`, `llm-connect`, and State Hub while allowing
+the engine to expose both programmatic and service interfaces.
+
+FastAPI is appropriate for the service boundary because State Hub already uses
+that stack locally, but it remains optional until `KONT-WP-0003` defines stable
+artifact, collection, storage, query, workflow, and context contracts.
+
+## Deferred Decisions
+
+- Durable storage backend selection beyond initial repository interfaces.
+- HTTP endpoint shape and versioning.
+- Whether an administrative CLI is needed.
+- Lockfile/SBOM source, once dependencies are installed in this repo.
+