docs: explain the problem HEnRY solves

README.md

@@ -18,6 +18,29 @@ prototype used MemGPT/Letta.
 > **Status: alpha.** The governed execution path is implemented and tested. Durable storage,
 > production identity and complete facilitator/mediator workflows remain on the roadmap.
 
+## The problem
+
+Organizations are not one knowledge base with one trust boundary. They are made of domains—such as
+HR, finance, legal or operations—with different owners, data, tools, policies and access rules. A
+request may need several of those domains, while no participant should automatically see the full
+user context or another domain's internal state.
+
+The usual approaches force an unsafe trade-off:
+
+| Approach | What breaks as domains grow |
+| --- | --- |
+| One assistant per domain | Users face multiple portals; teams duplicate infrastructure; cross-domain work stays manual |
+| One centralized assistant | It becomes over-privileged; ownership blurs; sensitive context accumulates; execution becomes hard to audit |
+| Provider-specific integrations | Capabilities and governance become coupled to a runtime, slowing replacement and reuse |
+
+The hard problem is therefore not simply routing a prompt to several agents. It is letting one task
+cross organizational boundaries while every domain retains authority over its capabilities and data,
+only the minimum authorized context is disclosed, and every delegation and result remains
+reconstructable.
+
+HEnRY addresses this as a governance problem above the execution runtime. Read the full
+[problem statement](docs/problem.md).
+
 ## Why HEnRY?
 
 Most agent frameworks answer **how to run an agent**. HEnRY answers the organizational questions
@@ -131,6 +154,7 @@ tests/                 Unit and integration coverage
 ## Documentation
 
 - [Documentation map](docs/README.md)
+- [Problem statement](docs/problem.md)
 - [Getting started](docs/getting-started.md)
 - [Domains and sovereignty](docs/concepts/domains.md)
 - [Controlled context sharing](docs/concepts/context-sharing.md)

docs/README.md

@@ -4,11 +4,12 @@ Start with the problem you are trying to solve, then move into contracts and imp
 
 ## Learn
 
-1. [Getting started](getting-started.md) — run the deterministic governance demo.
-2. [Domains and sovereignty](concepts/domains.md) — understand the primary HEnRY boundary.
-3. [Controlled context sharing](concepts/context-sharing.md) — understand visibility cones.
-4. [Architecture overview](architecture/overview.md) — connect contracts to services.
-5. [Provider adapters](providers/README.md) — integrate another execution runtime.
+1. [Problem statement](problem.md) — understand why cross-domain agent collaboration is hard.
+2. [Getting started](getting-started.md) — run the deterministic governance demo.
+3. [Domains and sovereignty](concepts/domains.md) — understand the primary HEnRY boundary.
+4. [Controlled context sharing](concepts/context-sharing.md) — understand visibility cones.
+5. [Architecture overview](architecture/overview.md) — connect contracts to services.
+6. [Provider adapters](providers/README.md) — integrate another execution runtime.
 
 ## Decisions and operations
 

docs/problem.md

@@ -0,0 +1,98 @@
+# The problem HEnRY solves
+
+Enterprise assistants are often introduced as isolated, single-domain applications: one assistant
+for HR, another for finance, another for legal, and so on. That model works for an initial use case,
+but it does not provide a safe or maintainable way to complete tasks that span organizational
+boundaries.
+
+HEnRY starts from a different premise: an organization is a federation of domains, not one flat
+knowledge base.
+
+## Domains are real boundaries
+
+A domain has its own:
+
+- accountable owner and governance process;
+- data, procedures, tools and business capabilities;
+- access rules, classifications and regulatory constraints;
+- internal agents, models, infrastructure and memory;
+- lifecycle and technology choices.
+
+These boundaries cannot be removed merely to make agent orchestration easier. In regulated or
+large organizations, least privilege requires each user and system participant to receive only the
+information relevant to its role and purpose. The HEnRY paper describes these permitted views as
+**visibility cones**.
+
+## Why common assistant architectures fail
+
+### Isolated domain assistants create silos
+
+Copying an assistant for every new domain fragments the user experience and the technology stack.
+Users must discover and operate multiple portals, shared features are implemented repeatedly, and
+cross-domain procedures remain manual or become a set of brittle point-to-point integrations. Each
+new domain increases the governance and integration burden.
+
+### A central super-agent creates excessive authority
+
+Combining every domain in one assistant improves discoverability but weakens boundaries. The
+central agent tends to accumulate broad credentials, raw context, tool access and conversation
+history. It becomes difficult to answer who authorized a disclosure, which domain owned an action,
+why a piece of context was available, or which agent contributed to a result.
+
+### Runtime-specific integrations create lock-in
+
+If organizational rules are embedded directly in prompts, tools or provider-specific sessions,
+changing the execution runtime requires rebuilding the control model. Different domains may also
+need different models or providers, so one runtime cannot be the organizational boundary.
+
+## The design question
+
+HEnRY asks:
+
+> How can one user objective be decomposed and executed across independently governed domains
+> without creating either disconnected silos or an all-powerful central agent?
+
+A satisfactory system must provide all of the following at the same time:
+
+1. **One interaction surface.** A user can express an objective without manually coordinating
+   domain-specific assistants.
+2. **Domain sovereignty.** Each domain continues to own its capabilities, policies, data and
+   implementation choices.
+3. **Controlled collaboration.** Cross-domain work occurs through explicit tasks and contracts,
+   rather than unrestricted agent access.
+4. **Minimum necessary context.** Every participant receives a purpose-bound projection instead of
+   the complete source context.
+5. **Replaceable execution.** Domains can select suitable models, agents and providers without
+   moving governance into those providers.
+6. **End-to-end accountability.** The system records decomposition, authorization, disclosure,
+   execution and result provenance so a task can be reconstructed.
+
+These requirements are in tension. Better collaboration often encourages broader sharing; stronger
+isolation often makes useful workflows harder. HEnRY exists to make that trade-off explicit,
+policy-controlled and auditable.
+
+## What HEnRY contributes
+
+HEnRY separates organizational governance from agent execution:
+
+- the **digital twin** represents the user and protects user-owned context;
+- the **facilitator** discovers capabilities and decomposes an objective into domain-scoped tasks;
+- the **mediator** governs temporary collaboration and context exchange across domains;
+- **domain agents** execute bounded capabilities under domain-owned rules;
+- **capability contracts** expose what a domain can do without exposing its internals;
+- **context grants** materialize expiring visibility cones for a recipient and purpose;
+- **audit records** connect policy decisions, grants, tasks, provider executions and results.
+
+The execution provider remains replaceable. OmniAgent is the default adapter today, while the
+original research prototype used MemGPT/Letta. Neither provider defines HEnRY's domain model or
+security boundary.
+
+## Scope
+
+HEnRY is intended for workflows where multiple agents or services must cooperate across meaningful
+ownership, privacy or policy boundaries. It is not required for a single assistant operating inside
+one trust domain, and it is not a substitute for an organization's identity, policy, data-governance
+or records-management systems. It integrates those controls into agent collaboration.
+
+The problem and original architecture are introduced in
+[HEnRY: A Multi-Agent System Framework for Multi-Domain Contexts](https://arxiv.org/abs/2410.12720).