AbstractRuntime 0.4.0__tar.gz → 0.4.1__tar.gz

abstractruntime-0.4.1/ACKNOWLEDGMENTS.md

@@ -0,0 +1,27 @@
+# Acknowledgments
+
+AbstractRuntime is designed to pair with the wider Abstract ecosystem and the open-source Python tooling community.
+
+This project depends on (and is shaped by) the following libraries.
+The canonical dependency list lives in `pyproject.toml`.
+
+## Runtime dependencies (core install)
+
+- **abstractsemantics** — structured schema registry support (declared in `pyproject.toml`, used in `src/abstractruntime/integrations/abstractmemory/effect_handlers.py` and VisualFlow execution wiring).
+
+## Optional integrations (extras)
+
+Installed only when you opt in to extras:
+- **abstractcore** — LLM + tools integration used by `abstractruntime[abstractcore]` (declared in `pyproject.toml`, implementation under `src/abstractruntime/integrations/abstractcore/*`, docs: `docs/integrations/abstractcore.md`).
+  - The AbstractCore integration uses **httpx** for remote mode (`src/abstractruntime/integrations/abstractcore/llm_client.py`) and **pydantic** for structured validation (`src/abstractruntime/integrations/abstractcore/effect_handlers.py`). These are provided by AbstractCore’s dependency set.
+- **abstractcore[tools]** — toolchain extra used by `abstractruntime[mcp-worker]` (declared in `pyproject.toml`) and intended to include HTML parsing dependencies (see comments in `pyproject.toml`).
+- **RestrictedPython** (optional) — used for sandboxed execution of VisualFlow “Code” nodes when available (`src/abstractruntime/visualflow_compiler/visual/code_executor.py`).
+
+## Build & test tooling
+
+- **hatchling** — build backend (`pyproject.toml` `[build-system]`).
+- **pytest** — test runner (`pytest.ini`, `tests/`).
+
+And thanks to everyone who reports bugs, discusses design tradeoffs, and contributes improvements.
+
+See also: `LICENSE`, `CONTRIBUTING.md`.

abstractruntime-0.4.1/ACKNOWLEDMENTS.md

@@ -0,0 +1,4 @@
+# Acknowledments (legacy filename)
+
+This project uses `ACKNOWLEDGMENTS.md` (correct spelling). Please refer to that file.
+

abstractruntime-0.4.1/CHANGELOD.md

@@ -0,0 +1,4 @@
+# Changelog (legacy filename)
+
+This project uses `CHANGELOG.md`. Please refer to that file.
+

{abstractruntime-0.4.0 → abstractruntime-0.4.1}/CHANGELOG.md

@@ -7,13 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+### Changed
+
+### Fixed
+
+## [0.4.1] - 2026-02-04
+
 ### Added
 - **Durable prompt metadata for EVENT waits**:
   - `WAIT_EVENT` effects may include optional `prompt`, `choices`, and `allow_free_text` fields.
   - The runtime persists these fields onto `WaitState` so hosts (including remote/thin clients) can render a durable ask+wait UX without relying on in-process callbacks.
 - **Rendering utilities** (`abstractruntime.rendering`):
   - `stringify_json(...)` + `JsonStringifyMode` to render JSON/JSON-ish values into strings with `none|beautify|minified` modes.
-  - `render_agent_trace_markdown(...)` to render runtime-owned `node_traces` scratchpads into a complete, review-friendly Markdown timeline (tool args + results untruncated).
+  - `render_agent_trace_markdown(...)` to render runtime-owned `node_traces` scratchpads into a complete, review-friendly Markdown timeline.
+- **Documentation refresh**:
+  - clearer entrypoints: `README.md` → `docs/getting-started.md`
+  - new reference docs: `docs/api.md`, `docs/faq.md`, `docs/architecture.md`
+  - maintainer-facing orientation: `llms.txt`, `llms-full.txt`
+  - new repo policies: `CONTRIBUTING.md`, `SECURITY.md`, `ACKNOWLEDGMENTS.md`
+
+### Fixed
+- Normalize AbstractCore tool specs for skim tools so `paths` is always an array parameter (improves JSON schema consistency for tool callers).
 
 ## [0.4.0] - 2025-01-06
 
@@ -203,15 +218,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Graph-Based Execution**: All workflows represented as state machines/graphs for visualization and composition
 - **JSON-Serializable State**: All run state and vars must be JSON-serializable for persistence
 
-#### Test Coverage
-- **81% Overall Coverage**: Comprehensive test suite with 57+ tests
-- **Integration Tests**: Tests for AbstractCore integration, subworkflows, trace propagation
-- **Core Tests**: Scheduler, snapshots, artifacts, pause/resume, retry/idempotency, ledger chain
-- **Storage Tests**: Queryable run store, durable toolsets
+#### Testing
+- Run the test suite with `python -m pytest -q` (see `docs/manual_testing.md`).
 
 #### Compatibility
 - **Python 3.10+**: Supports Python 3.10, 3.11, 3.12, and 3.13
-- **Development Status**: Planning/Alpha (moving toward Beta with 0.2.0)
 
 ### Known Limitations
 
@@ -236,5 +247,7 @@ AbstractRuntime is the durable execution substrate designed to pair with Abstrac
 
 Initial development version with basic proof-of-concept features.
 
-[0.2.0]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.2.0
+[Unreleased]: https://github.com/lpalbou/abstractruntime/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.4.1
+[0.4.0]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.4.0
 [0.0.1]: https://github.com/lpalbou/abstractruntime/releases/tag/v0.0.1

abstractruntime-0.4.1/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to AbstractRuntime
+
+Thanks for your interest in contributing!
+
+AbstractRuntime is a **durable workflow runtime** (interrupt → checkpoint → resume) with an append-only execution ledger.
+
+## Quick start (dev setup)
+
+Prereqs: **Python 3.10+**.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+
+# Full dev install (kernel + optional integrations used by tests/examples)
+python -m pip install -e ".[abstractcore,mcp-worker]"
+
+python -m pytest -q
+```
+
+## Repo map (source of truth)
+
+- Public exports: `src/abstractruntime/__init__.py` (keep this consistent with `docs/api.md`)
+- Core kernel (durable semantics): `src/abstractruntime/core/`
+- Durability backends: `src/abstractruntime/storage/`
+- Driver loop (in-process): `src/abstractruntime/scheduler/`
+- Optional integrations (extras): `src/abstractruntime/integrations/`
+- Tests: `tests/`
+
+Docs entrypoints:
+- `README.md` → `docs/getting-started.md`
+- Docs index: `docs/README.md`
+- Architecture: `docs/architecture.md`
+
+## Change guidelines
+
+### Code
+
+- Preserve durability invariants: values stored in `RunState.vars` must stay JSON-serializable (`src/abstractruntime/core/models.py`).
+- Add/adjust tests for new behavior (see `tests/`).
+- If you touch effect semantics, update `docs/architecture.md` and ensure handlers and models stay aligned.
+
+### Documentation
+
+Docs should be **user-facing**, **actionable**, and anchored to code (prefer referencing `src/...` paths for claims).
+
+When behavior changes, update:
+- `docs/api.md` (public API surface + imports)
+- `docs/getting-started.md` (onboarding examples)
+- `docs/architecture.md` (semantics/invariants)
+- `CHANGELOG.md` (user-visible changes)
+
+## Releases
+
+- Bump `version` in `pyproject.toml`
+- Add a dated section to `CHANGELOG.md` (Keep a Changelog format)
+

abstractruntime-0.4.1/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: AbstractRuntime
+Version: 0.4.1
+Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
+Project-URL: AbstractCore (website), https://www.abstractcore.ai/
+Project-URL: AbstractRuntime (GitHub), https://github.com/lpalbou/abstractruntime
+Author: Laurent-Philippe Albou
+License: MIT
+License-File: LICENSE
+Keywords: agents,checkpoint,durable,graph,llm,resume,workflow
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: abstractsemantics>=0.0.1
+Provides-Extra: abstractcore
+Requires-Dist: abstractcore>=2.6.8; extra == 'abstractcore'
+Provides-Extra: mcp-worker
+Requires-Dist: abstractcore[tools]>=2.6.8; extra == 'mcp-worker'
+Description-Content-Type: text/markdown
+
+# AbstractRuntime
+
+**AbstractRuntime** is a durable workflow runtime (interrupt → checkpoint → resume) with an append-only execution ledger.
+
+It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
+
+**Version:** 0.4.1 (`pyproject.toml`) • **Python:** 3.10+
+
+## Install
+
+Core runtime:
+
+```bash
+pip install abstractruntime
+```
+
+AbstractCore integration (LLM + tools):
+
+```bash
+pip install "abstractruntime[abstractcore]"
+```
+
+MCP worker entrypoint (default toolsets over stdio):
+
+```bash
+pip install "abstractruntime[mcp-worker]"
+```
+
+## Quick start (pause + resume)
+
+```python
+from abstractruntime import Effect, EffectType, Runtime, StepPlan, WorkflowSpec
+from abstractruntime.storage import InMemoryLedgerStore, InMemoryRunStore
+
+
+def ask(run, ctx):
+    return StepPlan(
+        node_id="ask",
+        effect=Effect(
+            type=EffectType.ASK_USER,
+            payload={"prompt": "Continue?"},
+            result_key="user_answer",
+        ),
+        next_node="done",
+    )
+
+
+def done(run, ctx):
+    return StepPlan(node_id="done", complete_output={"answer": run.vars.get("user_answer")})
+
+
+wf = WorkflowSpec(workflow_id="demo", entry_node="ask", nodes={"ask": ask, "done": done})
+rt = Runtime(run_store=InMemoryRunStore(), ledger_store=InMemoryLedgerStore())
+
+run_id = rt.start(workflow=wf)
+state = rt.tick(workflow=wf, run_id=run_id)
+assert state.status.value == "waiting"
+
+state = rt.resume(
+    workflow=wf,
+    run_id=run_id,
+    wait_key=state.waiting.wait_key,
+    payload={"text": "yes"},
+)
+assert state.status.value == "completed"
+```
+
+## What’s included (v0.4.1)
+
+Kernel (dependency-light):
+- workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
+- durable execution: `Runtime.start/tick/resume` (`src/abstractruntime/core/runtime.py`)
+- durable waits/events: `WAIT_EVENT`, `WAIT_UNTIL`, `ASK_USER`, `EMIT_EVENT`
+- append-only ledger (`StepRecord`) + node traces (`vars["_runtime"]["node_traces"]`)
+- retries/idempotency hooks: `src/abstractruntime/core/policy.py`
+
+Durability + storage:
+- stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
+- artifacts + offloading (store large payloads by reference)
+- snapshots/bookmarks (`docs/snapshots.md`)
+- tamper-evident hash-chained ledger (`docs/provenance.md`)
+
+Drivers + distribution:
+- scheduler: `create_scheduled_runtime()` (`src/abstractruntime/scheduler/*`)
+- VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
+- run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
+
+Optional integrations:
+- AbstractCore (LLM + tools): `docs/integrations/abstractcore.md`
+- comms toolset gating (email/WhatsApp/Telegram): `docs/tools-comms.md`
+
+## Built-in scheduler (zero-config)
+
+```python
+from abstractruntime import create_scheduled_runtime
+
+sr = create_scheduled_runtime()
+run_id, state = sr.run(my_workflow)
+
+if state.status.value == "waiting":
+    state = sr.respond(run_id, {"answer": "yes"})
+
+sr.stop()
+```
+
+For persistent storage:
+
+```python
+from abstractruntime import create_scheduled_runtime, JsonFileRunStore, JsonlLedgerStore
+
+sr = create_scheduled_runtime(
+    run_store=JsonFileRunStore("./data"),
+    ledger_store=JsonlLedgerStore("./data"),
+)
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](docs/getting-started.md) | Install + first durable workflow |
+| [API Reference](docs/api.md) | Public API surface (imports + pointers) |
+| [Docs Index](docs/README.md) | Full docs map (guides + reference) |
+| [FAQ](docs/faq.md) | Common questions and gotchas |
+| [Architecture](docs/architecture.md) | Component map + diagrams |
+| [Overview](docs/proposal.md) | Design goals, core concepts, and scope |
+| [Integrations](docs/integrations/) | Integration guides (AbstractCore) |
+| [Snapshots](docs/snapshots.md) | Named checkpoints for run state |
+| [Provenance](docs/provenance.md) | Tamper-evident ledger documentation |
+| [Evidence](docs/evidence.md) | Artifact-backed evidence capture for web/command tools |
+| [Limits](docs/limits.md) | `_limits` namespace and RuntimeConfig |
+| [WorkflowBundles](docs/workflow-bundles.md) | `.flow` bundle format (VisualFlow distribution) |
+| [MCP Worker](docs/mcp-worker.md) | `abstractruntime-mcp-worker` CLI |
+| [Changelog](CHANGELOG.md) | Release notes |
+| [Contributing](CONTRIBUTING.md) | How to build/test and submit changes |
+| [Security](SECURITY.md) | Responsible vulnerability reporting |
+| [Acknowledgments](ACKNOWLEDGMENTS.md) | Credits |
+| [ROADMAP](ROADMAP.md) | Prioritized next steps |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[abstractcore,mcp-worker]"
+python -m pytest -q
+```
+
+See `CONTRIBUTING.md` for contribution guidelines and doc conventions.

abstractruntime-0.4.1/README.md

@@ -0,0 +1,150 @@
+# AbstractRuntime
+
+**AbstractRuntime** is a durable workflow runtime (interrupt → checkpoint → resume) with an append-only execution ledger.
+
+It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
+
+**Version:** 0.4.1 (`pyproject.toml`) • **Python:** 3.10+
+
+## Install
+
+Core runtime:
+
+```bash
+pip install abstractruntime
+```
+
+AbstractCore integration (LLM + tools):
+
+```bash
+pip install "abstractruntime[abstractcore]"
+```
+
+MCP worker entrypoint (default toolsets over stdio):
+
+```bash
+pip install "abstractruntime[mcp-worker]"
+```
+
+## Quick start (pause + resume)
+
+```python
+from abstractruntime import Effect, EffectType, Runtime, StepPlan, WorkflowSpec
+from abstractruntime.storage import InMemoryLedgerStore, InMemoryRunStore
+
+
+def ask(run, ctx):
+    return StepPlan(
+        node_id="ask",
+        effect=Effect(
+            type=EffectType.ASK_USER,
+            payload={"prompt": "Continue?"},
+            result_key="user_answer",
+        ),
+        next_node="done",
+    )
+
+
+def done(run, ctx):
+    return StepPlan(node_id="done", complete_output={"answer": run.vars.get("user_answer")})
+
+
+wf = WorkflowSpec(workflow_id="demo", entry_node="ask", nodes={"ask": ask, "done": done})
+rt = Runtime(run_store=InMemoryRunStore(), ledger_store=InMemoryLedgerStore())
+
+run_id = rt.start(workflow=wf)
+state = rt.tick(workflow=wf, run_id=run_id)
+assert state.status.value == "waiting"
+
+state = rt.resume(
+    workflow=wf,
+    run_id=run_id,
+    wait_key=state.waiting.wait_key,
+    payload={"text": "yes"},
+)
+assert state.status.value == "completed"
+```
+
+## What’s included (v0.4.1)
+
+Kernel (dependency-light):
+- workflow graphs: `WorkflowSpec` (`src/abstractruntime/core/spec.py`)
+- durable execution: `Runtime.start/tick/resume` (`src/abstractruntime/core/runtime.py`)
+- durable waits/events: `WAIT_EVENT`, `WAIT_UNTIL`, `ASK_USER`, `EMIT_EVENT`
+- append-only ledger (`StepRecord`) + node traces (`vars["_runtime"]["node_traces"]`)
+- retries/idempotency hooks: `src/abstractruntime/core/policy.py`
+
+Durability + storage:
+- stores: in-memory, JSON/JSONL, SQLite (`src/abstractruntime/storage/*`)
+- artifacts + offloading (store large payloads by reference)
+- snapshots/bookmarks (`docs/snapshots.md`)
+- tamper-evident hash-chained ledger (`docs/provenance.md`)
+
+Drivers + distribution:
+- scheduler: `create_scheduled_runtime()` (`src/abstractruntime/scheduler/*`)
+- VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
+- run history export: `export_run_history_bundle(...)` (`src/abstractruntime/history_bundle.py`)
+
+Optional integrations:
+- AbstractCore (LLM + tools): `docs/integrations/abstractcore.md`
+- comms toolset gating (email/WhatsApp/Telegram): `docs/tools-comms.md`
+
+## Built-in scheduler (zero-config)
+
+```python
+from abstractruntime import create_scheduled_runtime
+
+sr = create_scheduled_runtime()
+run_id, state = sr.run(my_workflow)
+
+if state.status.value == "waiting":
+    state = sr.respond(run_id, {"answer": "yes"})
+
+sr.stop()
+```
+
+For persistent storage:
+
+```python
+from abstractruntime import create_scheduled_runtime, JsonFileRunStore, JsonlLedgerStore
+
+sr = create_scheduled_runtime(
+    run_store=JsonFileRunStore("./data"),
+    ledger_store=JsonlLedgerStore("./data"),
+)
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](docs/getting-started.md) | Install + first durable workflow |
+| [API Reference](docs/api.md) | Public API surface (imports + pointers) |
+| [Docs Index](docs/README.md) | Full docs map (guides + reference) |
+| [FAQ](docs/faq.md) | Common questions and gotchas |
+| [Architecture](docs/architecture.md) | Component map + diagrams |
+| [Overview](docs/proposal.md) | Design goals, core concepts, and scope |
+| [Integrations](docs/integrations/) | Integration guides (AbstractCore) |
+| [Snapshots](docs/snapshots.md) | Named checkpoints for run state |
+| [Provenance](docs/provenance.md) | Tamper-evident ledger documentation |
+| [Evidence](docs/evidence.md) | Artifact-backed evidence capture for web/command tools |
+| [Limits](docs/limits.md) | `_limits` namespace and RuntimeConfig |
+| [WorkflowBundles](docs/workflow-bundles.md) | `.flow` bundle format (VisualFlow distribution) |
+| [MCP Worker](docs/mcp-worker.md) | `abstractruntime-mcp-worker` CLI |
+| [Changelog](CHANGELOG.md) | Release notes |
+| [Contributing](CONTRIBUTING.md) | How to build/test and submit changes |
+| [Security](SECURITY.md) | Responsible vulnerability reporting |
+| [Acknowledgments](ACKNOWLEDGMENTS.md) | Credits |
+| [ROADMAP](ROADMAP.md) | Prioritized next steps |
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -e ".[abstractcore,mcp-worker]"
+python -m pytest -q
+```
+
+See `CONTRIBUTING.md` for contribution guidelines and doc conventions.

abstractruntime-0.4.1/ROADMAP.md

@@ -0,0 +1,36 @@
+# AbstractRuntime Roadmap
+
+## Current status (v0.4.1)
+
+AbstractRuntime provides a durable workflow kernel plus optional integrations:
+- durable execution: `Runtime.start/tick/resume`, explicit `WaitState` (`src/abstractruntime/core/runtime.py`)
+- append-only ledger (`StepRecord`) + persistent stores (JSON/JSONL, SQLite) (`src/abstractruntime/storage/*`)
+- built-in scheduler (`Scheduler`, `ScheduledRuntime`) (`src/abstractruntime/scheduler/*`)
+- snapshots/bookmarks (`src/abstractruntime/storage/snapshots.py`)
+- tamper-evident hash-chained ledger (`src/abstractruntime/storage/ledger_chain.py`)
+- artifacts + offloading for large payloads (`src/abstractruntime/storage/artifacts.py`, `src/abstractruntime/storage/offloading.py`)
+- retries/idempotency hooks (`src/abstractruntime/core/policy.py`)
+- VisualFlow compiler + WorkflowBundles (`src/abstractruntime/visualflow_compiler/*`, `src/abstractruntime/workflow_bundle/*`)
+- AbstractCore integration for `LLM_CALL` / `TOOL_CALLS` (`docs/integrations/abstractcore.md`)
+
+## Near-term priorities
+
+These are tracked in `docs/backlog/planned/`:
+
+1. **Signatures and keys** — non-forgeable provenance (beyond tamper-evidence)  
+   `docs/backlog/planned/008_signatures_and_keys.md`
+
+2. **Remote tool worker executor** — first-class worker boundary for tool execution  
+   `docs/backlog/planned/014_remote_tool_worker_executor.md`
+
+3. **Limit warnings + observability events** — surface `_limits` warnings durably/streaming  
+   `docs/backlog/planned/017_limit_warnings_and_observability.md`
+
+4. **Agent integration improvements** — reduce friction for external agent loops building on runtime  
+   `docs/backlog/planned/015_agent_integration_improvements.md`
+
+## Longer-term (not scheduled)
+
+- distributed scheduling primitives (beyond in-process polling)
+- workflow versioning/migration patterns for long-lived runs and snapshot restore
+- stronger reproducibility contracts for replays (workflow snapshotting + run history bundles)

abstractruntime-0.4.1/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues **privately**.
+
+Preferred channel:
+- Use **GitHub Security Advisories** / the repository’s “Report a vulnerability” feature (private).
+
+Include as much of the following as you can:
+- affected versions (from `pyproject.toml` / `CHANGELOG.md`)
+- impact and realistic attack scenario
+- minimal reproduction steps or proof-of-concept
+- environment details (OS, Python version, storage backend used)
+
+## Coordinated disclosure
+
+- Do not open public issues/PRs for security vulnerabilities.
+- Avoid data exfiltration, service disruption, or destructive testing; keep verification to the minimum needed.
+
+## Non-security bugs
+
+If you are unsure whether an issue is security-related, prefer reporting it privately first.
+

abstractruntime-0.4.1/docs/README.md

@@ -0,0 +1,37 @@
+# Documentation
+
+This folder contains **user-facing docs** (how to use AbstractRuntime) and **maintainer docs** (ADRs/backlog).
+
+## Start here
+
+- `../README.md` — install + quick start
+- `getting-started.md` — first steps (recommended)
+- `api.md` — public API surface (imports + pointers)
+- `architecture.md` — how the runtime is structured (with diagrams)
+- `proposal.md` — design goals and scope boundaries
+
+## Guides
+
+- `faq.md` — common questions (recommended)
+- `manual_testing.md` — manual smoke tests and how to run the test suite
+- `integrations/abstractcore.md` — wiring `LLM_CALL` / `TOOL_CALLS` via AbstractCore
+- `tools-comms.md` — enabling the optional comms toolset (email/WhatsApp/Telegram)
+
+## Features (reference)
+
+- `evidence.md` — artifact-backed evidence capture for external-boundary tools
+- `mcp-worker.md` — MCP worker CLI (`abstractruntime-mcp-worker`)
+- `snapshots.md` — snapshot/bookmark model and stores
+- `provenance.md` — tamper-evident hash-chained ledger
+- `limits.md` — runtime-aware `_limits` namespace and APIs
+- `workflow-bundles.md` — `.flow` bundle format (VisualFlow distribution)
+
+## Maintainers
+
+- `../CHANGELOG.md` — release notes
+- `../CONTRIBUTING.md` — how to build/test and submit changes
+- `../SECURITY.md` — responsible vulnerability reporting
+- `../ACKNOWLEDGMENTS.md` — credits
+- `../ROADMAP.md` — prioritized next steps
+- `adr/README.md` — architectural decisions (why)
+- `backlog/README.md` — implemented and planned work items (what/how)