@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0-rc.604.2

package/IMPLEMENTATION.md

@@ -10,20 +10,68 @@ supported entry point is the package root (`import { ... } from "@indexnetwork/p
 deep imports are not part of the contract. Every symbol is re-exported explicitly from
 `src/index.ts` and tagged with a stability tier:
 
-- **Stable** — interfaces, graph factories, agents, `createMcpServer`, the
-  tool/runtime helpers, and shared schemas. Breaking changes require a major bump.
+- **Stable** — interfaces, graph factories, agents, and shared schemas.
+  Breaking changes require a major bump.
 - **Experimental** (`@experimental`) — advanced graph-state types and internal
   helpers; may change in a minor release.
 
 See [STABILITY.md](./STABILITY.md) for the full policy and the deprecation path,
 and [CHANGELOG.md](./CHANGELOG.md) for release history.
 
-Internal source is domain-first: `signals`, `communities`, `questions`,
-`participant-agents`, `contacts`, and `integrations`; opportunity and negotiation
-place state/contracts in `domain/` and workflows/tools in `application/`. The
-`intents` capability is instead organized by function behind a single exported
-class, `Intents`: files sit flat and named for what they do, with `graph/` and
-`intake/` the two multi-file stages that keep a directory.
+Private source under `src/internal/` is domain-first: `agents`, `networks`,
+`opportunities`, with `shared` for cross-cutting model and scope
+helpers. The `intents` capability is
+organized by function behind a single exported class, `Intents`: files sit flat
+and named for what they do, with `graph/` the one multi-file stage
+that keep a directory.
+
+`Negotiations` is the autonomous participation capability. It observes current
+state and returns protocol guidance, available actions, and block reasons. Its
+execute path passes a pure protocol decision function into the host's transaction:
+the host locks current membership, intent, and negotiation state, evaluates the
+function, and atomically applies the turn and opportunity transition.
+`openCounterparties` likewise receives the protocol's opening decision callback.
+The protocol enforces 12 total turns, leaving exhausted matches undecided, and
+A2A agreement only advances to pending owner review. `NegotiationContextDatabase`
+continues to provide scoped turn logs for opportunity presentation.
+
+Personal-agent reasoning and H2A communication live in the independent
+`@indexnetwork/agent` package. The API imports both libraries and supplies
+persistence, principal context, models, and events. The scenario TUI uses the same
+protocol capability with memory storage. Neither library imports the other.
+
+## Boundary model
+
+The package is migrating incrementally to a protocol kernel. `protocol/`
+contains portable, framework-free contracts and shared protocol instructions; `platform/` contains host-facing
+ports and supported runtime hooks; and `capabilities/` exposes small named
+behavior surfaces. Graphs, internal model prompts, retrieval, and agent helpers remain
+private implementation. These are source boundaries only: import supported
+symbols from `@indexnetwork/protocol`, not source subpaths. See
+[docs/protocol-kernel.md](./docs/protocol-kernel.md) for migration status.
+
+## Shared protocol instructions
+
+[`src/protocol/protocol.prompt.ts`](./src/protocol/protocol.prompt.ts) owns shared
+protocol instruction text in named constants. The module depends only
+on the negotiation limits, with no models, hosts, environment variables, or
+transport implementations.
+
+| Prompt or content | Consumer |
+|---|---|
+| `NEGOTIATION_GUIDANCE` | `protocol/negotiation.rules.ts`: `observeNegotiation` returns it to negotiation hosts; also the canonical `negotiations` topic |
+| `CANONICAL_GUIDANCE_SUMMARY`, `CANONICAL_GUIDANCE_TOPICS`, `CANONICAL_GUIDANCE_TOPICS_CONTENT` | The host's `GET /api/docs`: summary, topic metadata, and canonical sections |
+
+The host picks the topic and shapes the response.
+`negotiation.rules.ts` keeps validation and transitions. Guidance and enforcement
+share limits from
+[`src/protocol/negotiation.constants.ts`](./src/protocol/negotiation.constants.ts).
+Internal model prompts and personal-agent prompt composition stay with their
+existing owners.
+
+These paths describe internal ownership, not new public APIs. The package root
+continues to export `NEGOTIATION_GUIDANCE`, `NEGOTIATION_MAX_TURNS`, and
+`NEGOTIATION_MESSAGE_LIMIT` directly from their owning modules.
 
 
 ## Install
@@ -38,118 +86,55 @@ npm install @indexnetwork/protocol
 
 The package reads `OPENROUTER_API_KEY` (required), `CHAT_MODEL`, and `CHAT_REASONING_EFFORT` from environment variables. No startup call is needed.
 
-Environment variables are the supported way to configure models. `CHAT_MODEL` and `CHAT_REASONING_EFFORT` (`minimal | low | medium | high | xhigh`) drive the built-in chat runtime (`ChatGraphFactory` / `ChatAgent`); every other protocol agent — evaluators, generators, miners — reads `OPENROUTER_API_KEY` from the environment.
+Environment variables are the supported way to configure models. `CHAT_MODEL` and `CHAT_REASONING_EFFORT` (`minimal | low | medium | high | xhigh`) drive the default model; every protocol agent reads `OPENROUTER_API_KEY` from the environment.
 
-There is a per-instance `modelConfig` (chat model, reasoning effort, `apiKey`, `baseURL`) that `ChatAgent` reads off the resolved tool context, but it lives on the internal composition types (`ToolContext` / `ProtocolDeps`), not on `ToolDeps`, and those types are not exported. **Programmatic model override is therefore not part of the public contract in 15.0.0** — use the environment variables. If you need a typed override path, open an issue rather than reaching through a deep import.
+Programmatic model override is not part of the public contract — use the environment variables. If you need a typed override path, open an issue rather than reaching through a deep import.
 
 ### 2. Implement the adapters
 
 The package defines interfaces — your application provides the concrete implementations.
 
-**Required** (always needed by the tool registry):
+**Required** (always needed by the graphs):
 
 | Interface | Responsibility |
 |---|---|
-| `ChatGraphCompositeDatabase` | Core data access (users, intents, indexes/networks, opportunities) |
+| `CompositeDatabase` | Core data access (users, intents, networks, opportunities) |
 | `UserDatabase` / `SystemDatabase` | Context-bound databases built by `createUserDatabase` / `createSystemDatabase` |
 | `Embedder` | Vector embeddings for semantic search |
 | `Scraper` | Web content extraction |
-| `Cache` / `HydeCache` | Result caching (HyDE may share the general cache) |
-| `IntegrationAdapter` | OAuth and external tool actions |
-| `IntentGraphQueue` | Background intent processing queue |
-| `ContactServiceAdapter` | Contact management |
-| `ChatSessionReader` | Load conversation history |
+| `Cache` / `OpportunityCache` | Presentation/result caching |
+| `IntentFollowUp` | Lifecycle follow-up (`scoreIntent`, `onIntentSaved`, `onIntentArchived`, `onIntentResumed`) |
 | `ProfileEnricher` | Enrich profiles from external sources |
-| `NegotiationGraphDatabase` | Negotiation state persistence |
+| `NegotiationDatabase` | Current negotiation state and atomic commit with the supplied protocol decision function |
+| `NegotiationContextDatabase` | Read-only negotiation turn log, for opportunity presentation (folded into `CompositeDatabase`) |
 
 **Optional** (enable specific capabilities; omit to run without that feature):
 
 | Interface | Responsibility |
 |---|---|
-| `AgentDatabase` | Agent registry CRUD (agents, transports, permissions) |
-| `AgentDispatcher` | Resolves and invokes personal agents during negotiation turns — required to register the negotiation tools |
-| `McpAuthResolver` | Resolves `{ userId, agentId }` from an incoming MCP HTTP request (MCP server only) |
-| `DeliveryLedger` | Commits OpenClaw opportunity-delivery rows |
-| `EnrichmentRunStore` / `EnrichmentRunQueue` | Persist and execute async MCP enrichment runs |
-| `MintConnectLink` | Mints short connect links for opportunity accepts |
-| `ChatSummaryReader` | Read-through chat-session digest |
-| `ChatMessageWriter` | Writes user messages into the most-recent chat session (MCP elicitation) |
-| `QuestionGeneratorReader` / `QuestionerDatabase` | Decision-question generation and persistence |
-| `NegotiationSummaryReader` | Negotiation-digest summarization (falls back to deterministic digests) |
+| `AgentDatabase` | Agent registry CRUD (agents, permissions) |
 
 All interfaces are exported from the package root — import them with `import type { ... } from "@indexnetwork/protocol"`.
 
-### 3. Create tools
-
-Two entry points are supported, both taking a single dependency object built
-from the adapters above.
-
-`createMcpServer` is the complete integration: it composes every capability's
-tools internally, applies the authorization policy, and returns a ready MCP
-server.
-
-```typescript
-import { createMcpServer, CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS } from "@indexnetwork/protocol";
-
-const server = createMcpServer(
-  deps,                // ToolDeps + the opportunity owner-approval port
-  authResolver,        // McpAuthResolver
-  scopedDepsFactory,   // ScopedDepsFactory — builds per-user scoped userDb/systemDb
-  CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS,
-  authorizationObserver, // optional McpAuthorizationObserver
-);
-```
-
-`createToolRegistry` is the lower-level surface for hosts running their own
-runtime. It returns a `Map` of tool name to `RawToolDefinition` — raw async
-handlers taking `{ context, query }` — which you invoke through
-`invokeToolRuntime`:
-
-```typescript
-import { createToolRegistry, invokeToolRuntime, resolveChatContext } from "@indexnetwork/protocol";
-
-const registry = createToolRegistry(deps, { surface: "mcp" }); // omit `surface` for the full REST set
-
-const context = await resolveChatContext({
-  database,                 // the ChatGraphCompositeDatabase reads listed above
-  userId: "user-uuid",
-  networkId,                // optional — scopes tools to one network
-  sessionId,                // optional — enables draft opportunities
-});
-
-const tool = registry.get("search_intents")!;
-const result = await invokeToolRuntime({
-  toolName: tool.name,
-  tool,
-  context,
-  query: { /* validated against tool.schema */ },
-});
-```
+### 3. Compile the graphs
 
-The dependency object carries the required adapters listed above; optional
-capabilities default to a degraded-but-functional mode when omitted (for
-example, without `agentDispatcher` the negotiation tools are not registered).
+Intent/network graph factories take the adapters above and return compiled LangGraphs.
+Opportunity read and lifecycle operations are plain async functions. The database ports
+`updateOpportunityStatus(id, status, acceptedBy?)` and
+`stampOpportunityActorAction(id, actorUserId, status, acceptedBy?)` do not capture
+outcome feedback or accept an outbox. Negotiation outcomes remain part of the
+negotiation state and presentation contracts.
 
-The per-capability tool factories behind these entry points
-(`createChatTools`, `createIntentTools`, `createNegotiationTools`, …) are
-package-internal as of 15.0.0 and are not part of the supported surface.
-`createEnrichmentTools` remains exported for hosts that run enrichment on its
-own worker, separately from the chat runtime.
+Optional capabilities default to a
+degraded-but-functional mode when omitted.
 
 ## Graphs
 
-For direct graph invocation (bypassing the tool layer), a `*GraphFactory` class is exported for each workflow:
+A `*GraphFactory` class is exported for each workflow:
 
 ```typescript
 import {
-  ChatGraphFactory,
-  OpportunityGraphFactory,
-  EnrichmentGraphFactory,
-  PremiseGraphFactory,
-  NegotiationGraphFactory,
-  HydeGraphFactory,
   RadarGraphFactory,
-  MaintenanceGraphFactory,
 } from "@indexnetwork/protocol";
 ```
 
@@ -162,24 +147,32 @@ The intent and community graphs are the exceptions: they are reached through the
 
 | Factory | Workflow |
 |---|---|
-| `ChatGraphFactory` | ReAct chat loop — LLM calls tools, responds to the user |
-| `OpportunityGraphFactory` | Background matching: search, evaluate (valency), rank, persist |
-| `EnrichmentGraphFactory` | Enrich users (scrape + embed) and decompose into premises |
-| `PremiseGraphFactory` | Decompose and index a user's premises |
-| `NegotiationGraphFactory` | Multi-turn bilateral negotiation flows |
-| `HydeGraphFactory` | Generate hypothetical documents and embed them (cache-aware) |
 | `RadarGraphFactory` | Build the radar view: flat presenter-card list, optionally intent-scoped |
-| `MaintenanceGraphFactory` | Periodic maintenance (feed health, opportunity expiration) |
 
-### Persisted chat personas
+## On-demand discovery
 
-`ChatGraphFactory.withPersona()` keeps the runtime neutral while selecting an exported persona configuration. `SIGNAL_PERSONA` and `ONBOARDING_PERSONA` each own an exact positive tool allowlist; shared tools added later remain unavailable until reviewed. `ONBOARDING_PERSONA` reuses Signal's proposal-only, live-membership-narrowed `create_intent` contract and otherwise exposes only privacy consent, approved self-context preview/confirmation, guided questions, and validated completion. Hosts must persist the exported persona ID on session creation and treat it as authoritative on follow-ups.
+Discovery is not a protocol workflow and does not run when a signal is written.
+The host exposes it as a search: the owner's agent sends a query, the host
+embeds it and retrieves candidate signals from the communities that signal is
+shared in, and the agent picks which counterparties are worth an opportunity.
+Nothing is generated ahead of the query and nothing is cached.
+
+Protocol owns only what the picks are committed with. The host assigns
+`pairKeyOf(...)` and calls `openCounterparties(pairs, decideNegotiationOpening)`,
+which writes the opportunity and its negotiation; opening rules run inside the
+existing host transaction. Network/broadcast scope remains a protocol rule
+exposed through `resolveDiscoveryNetworkScope`, with context permissions handled
+by `renderDiscoveryNetworkContext`.
+
+`IntentFollowUp` therefore has no matching work to schedule: `onIntentSaved`,
+`onIntentArchived`, and `onIntentResumed` exist for hosts that want them and may
+do nothing. `scoreIntent` remains independent metadata work.
 
 ## Intents
 
 Signals are the protocol's base unit, and the whole capability ships as one
-class. `Intents` covers the lifecycle graph, semantic verification, network
-indexing, the guided intake interview, and the agent-facing intent tools.
+class. `Intents` covers the lifecycle graph, semantic verification, and payload
+clarification.
 
 ```typescript
 import { Intents } from "@indexnetwork/protocol";
@@ -187,8 +180,7 @@ import { Intents } from "@indexnetwork/protocol";
 const intents = new Intents({
   database,           // IntentGraphDatabase — required only by createGraph()
   embedder,           // EmbeddingGenerator
-  queue,              // IntentGraphQueue
-  questionerEnqueue,  // QuestionerEnqueueFn
+  followUp,           // IntentFollowUp
 });
 ```
 
@@ -198,108 +190,75 @@ first use, so an unused method costs nothing.
 
 | Method | Purpose |
 |---|---|
-| `createGraph()` | Compile the lifecycle graph — prep, infer, verify, reconcile, execute. Requires `database` |
+| `createGraph()` | Prepare and create exactly one new signal; explicitly read, update, archive, or transition existing signals. Requires `database` |
 | `verifyIntent(content, profileContext)` | Felicity conditions, speech-act classification, semantic entropy, specificity |
-| `indexIntent(intent, indexPrompt, memberPrompt, sourceName?, networkContext?)` | Score one signal against one network; `null` when the model call fails |
-| `generateIntakePack(input)` | The participant's intake brief and round-1 question |
-| `generateIntakeFollowUps(input)` | Plan and write the next follow-up questions |
-| `synthesizeIntake(input)` | Turn answered rounds into a description and card summary |
-| `Intents.createTools(defineTool, deps)` | Register the agent-facing intent tools |
-| `Intents.normalizeDescription(description)` | Normalize a description to its persisted form |
-| `Intents.FALLBACK_INTAKE_QUESTION` | The static round-1 question used when generation is unavailable |
+| `prepare({ payload, answers? })` | Fold recovery answers into the draft, then return `ready` with metadata or `needs_revision` with admission feedback and a dynamic recovery form; model failures throw for retry |
+| `scoreIntent(content, profileContext?)` | Measure saved text without admission filters; a negative verdict still returns metadata |
+| `Intents.normalizeDescription(description)` | Normalize an explicit update description; creation preserves text verbatim |
+
+Creation with `inputContent` prepares the description once and persists that exact
+text in a new record, even if a similar signal exists. Guided hosts call `prepare`
+until it returns `ready`, then issue their own authenticated preparation receipt
+bound to the owner and admitted draft. After authenticating the receipt, pass
+`preparation: { metadata }` to `createGraph().invoke()` alongside the final
+`inputContent`. If the user edited the text, pass `metadata: null`: permission to
+create survives revisions, but the draft's scores do not describe the edited text.
+Never accept this graph input directly from an untrusted client.
+
+No inference, admission, or reconciliation runs on prepared creation. The graph
+persists first and invokes `IntentFollowUp.scoreIntent` for revised text. Hosts
+must run scoring as best-effort background work, apply only metadata while the
+owner and payload still match, and leave the saved record usable on negative
+verdicts or failures. Authentication, nonempty text, length limits, and network
+membership remain the host's responsibility.
 
 ## Networks
 
 Communities ship the same way: one class covering the community lifecycle graph,
-the membership graph, signal↔community assignment, and the agent-facing
-community tools.
+the membership graph, and signal↔community assignment.
 
 ```typescript
 import { Networks } from "@indexnetwork/protocol";
 
 const networks = new Networks({
-  database,          // community, roster, and assignment persistence
-  indexer: intents,  // an `Intents` instance — scores a signal against a community
+  database, // community, roster, and assignment persistence
 });
 ```
 
-Both dependencies are optional; each method names what it requires, so a host
-that only registers tools can construct `new Networks()` with nothing.
+The dependency is optional; each method names what it requires, so
+construction never fails.
 
 | Method | Purpose |
 |---|---|
 | `createGraph()` | Compile the community lifecycle graph — create, read, update, delete. Requires `database` |
 | `createMembershipGraph()` | Compile the roster graph — add, list, remove members. Requires `database` |
-| `createAssignmentGraph()` | Compile signal↔community assignment, direct or model-evaluated. Requires `database` and `indexer` |
-| `Networks.createTools(defineTool, deps)` | Register the agent-facing community tools |
+| `createAssignmentGraph()` | Compile signal↔community assignment — link and unlink. Requires `database` |
 
-Assignment takes an `Intents` instance as its evaluator — the `indexer`
-dependency is narrowed to the single `indexIntent` method it calls.
+Assignment applies no scoring policy: a link exists because the signal's owner
+asked for it, so the row is written at score 1 with `mode: manual_override`.
 
-## MCP server
+## The REST API and the CLI
 
-The package exports a factory that registers every chat tool over the Model Context Protocol and attaches a canonical `instructions` block (`MCP_INSTRUCTIONS`) that every connecting runtime follows. The factory takes three arguments:
+External agents use `@indexnetwork/cli` against the host's REST API. Every
+capability is a named resource — `/api/intents`, `/api/networks`,
+`/api/opportunities`, `/api/negotiations`, `/api/conversations`, `/api/scrape`,
+`/api/docs` — and the user's single event stream is `GET /api/events`. Ownership
+and network membership checks live in the host's controllers and services.
 
-```typescript
-import { createMcpServer, type McpAuthResolver } from "@indexnetwork/protocol";
-
-const authResolver: McpAuthResolver = {
-  async resolveIdentity(req) {
-    // Look up the API key in `x-api-key` and return { userId, agentId? }.
-    // `agentId` should come from Better Auth token metadata so downstream
-    // tool handlers can attribute every call to a concrete agent identity.
-    return resolveFromApiKey(req);
-  },
-};
-
-const server = createMcpServer(
-  deps,
-  authResolver,
-  {
-    // Per-request factory for scoped user/system databases.
-    create: (userId, indexScope) => createScopedDeps(userId, indexScope),
-  },
-);
+```bash
+index --api-url https://protocol.index.network docs --json
+index --api-url https://protocol.index.network docs workflows --json
+index --api-url https://protocol.index.network intent list --json
 ```
 
-On every tool call the server:
-
-1. Extracts the HTTP request from the MCP `ServerContext`.
-2. Calls `authResolver.resolveIdentity(req)` to get `{ userId, agentId }`.
-3. Gates access through the canonical capability policy (`mcp/mcp.authorization-policy.ts`), decided per resolved principal BEFORE any context read or scoped-deps creation:
-   - **Enrollment-capable unregistered API keys** may see and call only `register_agent` — single-purpose across the entire registry.
-   - **Plain unregistered API keys** fail closed on every tool.
-   - **Registered active agents** retain their canonical permission- and network-scope-authorized domain tools, `read_docs`, and (for designated delivery agents) `confirm_opportunity_delivery`; within the agent-administration family (`MCP_AGENT_ADMIN_TOOLS`) they may see and call only `read_own_agent`, which returns the caller's own sanitized record and accepts no target.
-   - **Session humans** administer their owned agents (`register_agent`, `list_agents`, `update_agent`, `delete_agent`, `grant_agent_permission`, `revoke_agent_permission`) but are never offered the agent-only `read_own_agent`.
-   - Contact/Gmail-import tools, `scrape_url`, and the deprecated `*_user_profile`/`*_profile_run` aliases are not registered on the MCP surface at all (IND-596/597/598).
-4. Builds per-request scoped databases via `scopedDepsFactory` and invokes the tool handler through the shared runtime.
-
-### Runtime controls
-
-MCP tools are bounded by `ToolInvocationRuntime`:
-
-| Class | Default | Class override |
-|---|---:|---|
-| `fast` | 10 s | `MCP_TOOL_TIMEOUT_FAST_MS` |
-| `bounded_slow` | 45 s | `MCP_TOOL_TIMEOUT_BOUNDED_SLOW_MS` |
-| `async_candidate` | 50 s | `MCP_TOOL_TIMEOUT_ASYNC_CANDIDATE_MS` |
-
-Per-tool timeout overrides use `MCP_TOOL_TIMEOUT_<TOOL_NAME>_MS`. Tool outputs are capped by `MCP_TOOL_MAX_OUTPUT_BYTES` (default `1000000`) or `MCP_TOOL_MAX_OUTPUT_<TOOL_NAME>_BYTES`; inbound MCP request bodies are capped by the backend with `MCP_MAX_REQUEST_BYTES` (default `1000000`). Runtime failures return JSON text envelopes with stable `code` values: `TOOL_TIMEOUT`, `TOOL_CANCELLED`, or `TOOL_OUTPUT_TOO_LARGE`.
-
-
-### `MCP_INSTRUCTIONS`
-
-The instructions string is the single canonical behavioral contract for every runtime that connects to Index Network — voice, entity model, discovery-first rule, output rules, and the **Negotiation turn mode** block that tells a silent subagent how to handle a live negotiation turn when its session key is prefixed `index:negotiation:`. Plugin skills and bootstrap scripts do **not** redefine this guidance; they defer to whatever ships in `MCP_INSTRUCTIONS`.
-
-### Negotiation-facing tools
-
-Personal agents participate in bilateral negotiation via a small set of MCP tools:
-
-| Tool | Purpose |
-|---|---|
-| `get_negotiation` | Fetch the full turn history and assessment seed for a negotiation |
-| `list_negotiations` | List current and concluded agent negotiations with lifecycle-explicit opportunity and owner-action narration |
-| `respond_to_negotiation` | Submit a turn (propose / counter / accept / reject / question) |
+`GET /api/docs` serves canonical protocol guidance, including the resource
+routes and negotiation rules. Integrations read that guidance before writing.
+`GET /api/negotiations` lists the seat's negotiations across every opportunity;
+one negotiation is observed and turned through its opportunity, at
+`GET /api/opportunities/:id/negotiation` and
+`POST /api/opportunities/:id/negotiation/turns`, because exactly one is written
+with each opportunity. Personal-agent conversations require an intent scope and
+the current question ID when answering a pending question.
 
 ## Publishing
 

package/README.md

@@ -24,7 +24,6 @@ flowchart LR
     Participant --> Context[Context]
     Participant --> Signal[Signal]
 
-    Premises[Premises] --> Context
     Context --> Scope[Effective scope]
     Signal --> Scope
     Community[Community membership and norms] --> Scope
@@ -54,7 +53,7 @@ The graph is intentionally consent-centered: agents can construct context, disco
 3. **Semantic discovery** — matching is based on role fit, constraints, complementarity, and contextual relevance rather than exact keyword overlap.
 4. **Explainable surfacing** — every surfaced opportunity SHOULD include a legible reason: why these participants, why now, and what the next action might be.
 5. **Consent at relationship boundaries** — agents MAY discover and negotiate, but MUST NOT create or accept a relationship without explicit participant approval.
-6. **Agent interoperability** — first-party agents, personal agents, community agents, and external MCP clients SHOULD be able to participate under the same behavioral contract.
+6. **Agent interoperability** — first-party agents, personal agents, community agents, and external CLI clients SHOULD be able to participate under the same behavioral contract.
 
 ## Non-goals
 
@@ -74,8 +73,7 @@ The protocol does not attempt to be:
 | **Participant** | A human principal represented in the network. A participant may act directly or through one or more agents. |
 | **Agent** | A software actor authorized to act for a participant or community within a declared scope. |
 | **Signal** | A participant's actionable expression of intent: what they seek, offer, need, are building, are exploring, or can support. |
-| **Premise** | An atomic contextual claim about a participant, used to ground what signals are plausible or relevant. |
-| **Context** | A synthesized representation of premises, history, constraints, and community-specific relevance. |
+| **Context** | A synthesized representation of a participant's identity, history, constraints, and community-specific relevance. |
 | **Community** | A bounded discovery scope with membership, purpose, norms, and relevance criteria. |
 | **Membership** | The relationship between a participant and a community. Agents receive community authority through separate scoped permissions. |
 | **Candidate** | A possible counterpart or opportunity component identified during discovery but not yet surfaced. |
@@ -91,7 +89,6 @@ Some implementation APIs may expose historical names such as `intent`, `index`,
 erDiagram
     PARTICIPANT ||--o{ AGENT : authorizes
     PARTICIPANT ||--o{ SIGNAL : expresses
-    PARTICIPANT ||--o{ PREMISE : asserts
     PARTICIPANT ||--o{ CONTEXT : represented_by
     PARTICIPANT ||--o{ MEMBERSHIP : holds
     AGENT ||--o{ AGENT_PERMISSION : receives
@@ -180,7 +177,7 @@ A broader credential MUST NOT expand a narrower request. A narrower agent permis
 
 The protocol separates internal state from participant-facing language.
 
-Internal records MAY contain IDs, embeddings, scores, graph state, and tool names. Participant-facing responses MUST NOT expose these implementation details unless an identifier is directly actionable by the participant, such as a conversation identifier needed to open an accepted connection.
+Internal records MAY contain IDs, embeddings, scores, and graph state. Participant-facing responses MUST NOT expose these implementation details unless an identifier is directly actionable by the participant, such as a conversation identifier needed to open an accepted connection.
 
 ## Core objects
 
@@ -202,13 +199,13 @@ Signals have the following conceptual lifecycle:
 
 A signal MUST NOT be treated as active if it is outside the participant's authority, obviously insincere, unsafe to act on, or too vague to evaluate.
 
-### Premise and context
+### Context
 
-A premise is a small claim about a participant: background, role, current work, capability, location, affiliation, constraint, or declared preference. Premises ground discovery by determining whether a signal is plausible and which communities or counterparts are relevant.
+Context describes a participant: background, role, current work, capability, location, affiliation, constraints, and declared preferences. It grounds discovery by determining whether a signal is plausible and which communities or counterparts are relevant.
 
-Context is derived from premises. Context MAY be global to a participant or specific to a community. Community-specific context SHOULD emphasize facts relevant to that community's purpose and suppress irrelevant detail.
+Context MAY be global to a participant or specific to a community. Community-specific context SHOULD emphasize facts relevant to that community's purpose and suppress irrelevant detail.
 
-Premise and context updates SHOULD cause downstream discovery representations to refresh. Stale context SHOULD NOT be used when fresher participant-approved context exists.
+Context updates SHOULD cause downstream discovery representations to refresh. Stale context SHOULD NOT be used when fresher participant-approved context exists.
 
 ### Community
 
@@ -316,7 +313,7 @@ sequenceDiagram
 
 ### 1. Context construction
 
-The protocol collects participant-provided or participant-authorized material and turns it into premises and context. Context construction MUST preserve provenance and SHOULD prefer participant-approved information over inferred information.
+The protocol collects participant-provided or participant-authorized material and turns it into context. Context construction MUST preserve provenance and SHOULD prefer participant-approved information over inferred information.
 
 ### 2. Signal admission
 
@@ -328,7 +325,7 @@ The protocol determines the effective communities in which the signal can operat
 
 ### 4. Candidate generation
 
-The protocol generates candidates by comparing signals and context inside the effective scope. Candidate generation MAY use multiple strategies, including signal-to-signal, context-to-signal, premise-to-premise, semantic retrieval, and directed target construction.
+The protocol generates candidates by comparing signals and context inside the effective scope. Candidate generation MAY use multiple strategies, including signal-to-signal, context-to-signal, semantic retrieval, and directed target construction.
 
 Candidate generation is not surfacing. Candidate data MUST remain internal until evaluation and visibility checks pass.
 
@@ -352,7 +349,7 @@ A conforming agent MUST:
 
 - act only within its authenticated participant and community scope,
 - preserve participant consent at send, accept, and connection boundaries,
-- avoid exposing internal IDs, raw tool results, embeddings, scores, or database field names,
+- avoid exposing internal IDs, raw graph results, embeddings, scores, or database field names,
 - distinguish known facts from inferred context,
 - ask for clarification when required information is missing,
 - use the protocol vocabulary in participant-facing output,
@@ -389,21 +386,20 @@ The following invariants define the protocol's trust boundary:
 
 ## Interoperability
 
-The reference implementation exposes the protocol to agents through a Model Context Protocol (MCP) server and typed package APIs. MCP is the preferred interoperability surface for external agents because it provides tool discovery, runtime instructions, identity resolution, and bounded tool invocation.
+The reference implementation exposes the protocol through a REST API and typed package APIs. External agents use the Index CLI against those resources, reading canonical guidance from `GET /api/docs`. The API resolves identity and enforces ownership, network scope, and protocol rules.
 
 ```mermaid
 flowchart LR
-    ExternalAgent[External agent] -->|MCP tools| McpServer[Index Network MCP server]
+    ExternalAgent[External agent] --> CLI[Index CLI]
+    CLI --> HTTP[Index REST API]
     FirstPartyAgent[First-party agent] -->|typed runtime| Runtime[Protocol runtime]
-    PersonalAgent[Personal agent] -->|MCP tools or REST polling| McpServer
 
-    McpServer --> Identity[Identity resolution]
+    HTTP --> Identity[Identity resolution]
     Identity --> AgentGate[Agent registration and scope]
     AgentGate --> ScopedDeps[Scoped protocol dependencies]
     ScopedDeps --> Runtime
 
-    Runtime --> Tools[Protocol tools]
-    Tools --> Graphs[Discovery, context, signal, negotiation graphs]
+    Runtime --> Graphs[Discovery, context, signal graphs]
     Graphs --> Results[Bounded results]
     Results --> Runtime
     Runtime --> ParticipantOutput[Participant-facing output rules]
@@ -422,6 +418,6 @@ Implementations MAY expose additional transports, but they SHOULD preserve the s
 
 The canonical TypeScript implementation is `@indexnetwork/protocol`.
 
-- [IMPLEMENTATION.md](./IMPLEMENTATION.md) — package installation, adapters, graph factories, MCP server usage, and publishing.
+- [IMPLEMENTATION.md](./IMPLEMENTATION.md) — package installation, adapters, graph factories, REST API and CLI usage, and publishing.
 - [STABILITY.md](./STABILITY.md) — public API contract and SemVer policy.
 - [CHANGELOG.md](./CHANGELOG.md) — release history.

package/STABILITY.md

@@ -10,8 +10,7 @@ change. It is the reference behind the tier annotations in `src/index.ts`.
 - The supported entry points are the package root:
   `import { ... } from "@indexnetwork/protocol"` — and the **browser-safe
   subpaths** listed in `package.json` `exports` (as of 21.1.0:
-  `@indexnetwork/protocol/question-block` and
-  `@indexnetwork/protocol/question-block/fixture`). A browser-safe subpath
+  package root. There are no supported browser subpaths.
   exposes one shared-schema module whose only runtime dependency is `zod`, for
   consumers (the web client) that cannot load the node-only package root. The
   schema module's symbols are also re-exported from the root (the fixture is
@@ -30,6 +29,9 @@ change. It is the reference behind the tier annotations in `src/index.ts`.
   as a class rather than a re-export list — `intents` does, via `Intents` in
   `intents/intent.module.ts` — which makes the whole capability one exported
   symbol and its internal layout free to change without a contract change.
+- `protocol/`, `platform/`, `capabilities/`, and `internal/` are source-level
+  boundaries, not consumer subpaths. The sole supported Node import remains the
+  package root.
 
 ## Stability tiers
 
@@ -41,14 +43,17 @@ Covered by SemVer below. Breaking changes require a **major** bump.
 
 | Barrel section | What it is |
 |---|---|
-| **Public API** | `createToolRegistry`, model config helpers, tool/runtime helpers (`ResolvedToolContext`, `ToolDeps`, `invokeToolRuntime`, …), `requestContext`. |
-| **Interfaces** | Every `*.interface.ts` port you implement to inject infrastructure (databases, embedder, cache, scraper, queues, integration, agent dispatcher, …). |
-| **Shared schemas** | Zod schemas + inferred types that cross the boundary (questions, identity, network-assignment, chat-context, …). |
-| **Graph factories** | `*GraphFactory` classes (`ChatGraphFactory`, `OpportunityGraphFactory`, `NegotiationGraphFactory`, …). |
-| **Intents** | `Intents` — the whole signal capability as one class (lifecycle graph, verification, network indexing, guided intake, tools) plus `IntentsDeps` and the intake/indexer types. Replaced the six separate intent exports in 18.0.0. |
-| **Agents** | Structured LLM agents (`UserContextGenerator`, `IndexNegotiator`, `OpportunityEvaluator`, …). |
-| **MCP** | `createMcpServer` plus the types needed to call it: `ScopedDepsFactory`, `McpCapabilityPolicyOptions`, `CANONICAL_MCP_CAPABILITY_POLICY_OPTIONS`, `McpAuthorizationObserver`, `McpAuthorizationDenialEvent`. The rest of `mcp.authorization-policy.ts` is package-internal as of 15.0.0. |
-| **Capability tools** | `createEnrichmentTools` only. The other per-capability tool factories became package-internal in 15.0.0 — compose them through `createMcpServer` or `createToolRegistry`. |
+| **Public API** | Model config helpers, request scope helpers (`deriveAllowedNetworkIds`, `deriveDiscoveryNetworkIds`), `requestContext`. |
+| **Interfaces** | Every port you implement to inject infrastructure (databases, embedder, cache, scraper, integration, …). |
+| **Shared schemas** | Zod schemas + inferred types that cross the boundary (underspecification, identity, network-assignment, chat-context, …). |
+| **Graph factories** | `*GraphFactory` classes (for example, `RadarGraphFactory`). |
+| **Intents** | `Intents` — the whole signal capability as one class (lifecycle graph, verification, preparation) plus `IntentsDeps` and the `Prepare*` / `RecoveryField*` types. Replaced the six separate intent exports in 18.0.0. |
+| **Agents** | Structured LLM agents (`OpportunityEvaluator`, …). |
+
+`Negotiations`, `NegotiationDatabase`, the opening and turn decision functions,
+the observation function, and `negotiationTurnSchema` are stable. Hosts must
+evaluate supplied decision callbacks against locked current state and commit
+their effects atomically. `openCounterparties` takes the protocol opening callback.
 
 ### Experimental
 
@@ -57,7 +62,7 @@ a major bump. Use at your own risk and pin a version if you depend on them.
 
 | Area | What it is |
 |---|---|
-| **States** | Advanced graph-state shapes (`UserNegotiationContext`, `NegotiationTurn`, `NegotiationGraphLike`, …) exposed for advanced graph consumers. |
+| **States** | Advanced graph-state shapes exposed for advanced graph consumers. |
 | **Internal helpers** | Low-level support utilities re-exported for the backend's own use (selection/eval/evidence helpers) that are not part of the recommended integration surface. |
 
 > Most symbols in the barrel are consumed by the Index Network backend itself; a