# Embedded Semantics desktop-agent instructions

Version: embedded-semantics.desktop-agent-instructions.v1
Canonical service: https://embeddedsemantics.com

## Purpose
Use Embedded Semantics only when a workflow needs a stable governed ConceptCode for one human-language expression. The published registry record is authority. Embeddings, candidates, scores, and model output are not authority.

## Choose MCP or the direct API

### MCP-capable agent runtime
Connect to https://embeddedsemantics.com/mcp with modern stateless Streamable HTTP protocol 2026-07-28. POST `server/discover` first, then list or call the fixed read-only catalog. Every request repeats protocol version and client capabilities in `params._meta`; there is no legacy initialize handshake or protocol session. On HTTP 429, make no semantic assignment, honor `Retry-After`, and retry only under the caller's bounded transport policy. Full directions and exact headers: https://embeddedsemantics.com/mcp-guide. The guide and deployment manifest publish the active rate-limit contract.

## Connect in two requests
1. GET https://embeddedsemantics.com/api/v1/agent/connect with no request body. This stateless MVP bootstrap returns the canonical origin, current readiness, resolver URL, minimum-data rule, and fail-closed decision policy. It creates no session and accepts no client metadata or credentials.
2. POST only the exact expression and optional known language tag to https://embeddedsemantics.com/api/v1/resolve. Inspect the semantic result; HTTP success alone is not identity assignment.

Both surfaces use the same production resolver and registry authority.

## Why and where to use it
Use governed identity where meaning crosses a durable boundary: memory, API/event records, tool-routing inputs, cross-language handoffs, or audit evidence. Use it selectively, not on every conversational turn. The benefit comes from carrying the original expression, exact ConceptCode, and registryVersion together while preserving explicit no-code outcomes.

Read the adoption guide before choosing an integration point:
https://embeddedsemantics.com/api/v1/adoption-guide

Use one bounded recipe after choosing that point:
https://embeddedsemantics.com/api/v1/use-case-recipes

## When to call
- A stable ConceptCode is required for an expression at a durable semantic boundary.
- The caller can preserve an explicit unknown or ambiguous outcome.
- The caller needs current resolver readiness or a published Concept record.

## When not to call
- Ordinary question answering, summarization, translation, or writing where no ConceptCode is required.
- Permission, authorization, approval, or tool-execution decisions.
- Topic similarity, unconstrained classification, or an attempt to guess after abstention.

## Current readiness
- Positive exact resolution possible from the deployed public corpus: no
- Published concepts: 0
- Reviewed exact expressions: 0
- Governed public bundle complete: false
- Governed public bundle ID: embedded-semantics.public-registry-prerelease
- Governed public bundle SHA-256: 30811e375cdfc7c92828270aedd9bfde96dc92cf190096ad6bc6772de2fc995f
- Semantic runtime configured: false
- Arbitrary-query semantic resolution: not_production_active

Read live status before assuming a positive resolution is available:
https://embeddedsemantics.com/api/v1/status

## Before integration
Select exactly one canonical recipe and run all six fixed local fixtures with the dependency-free readiness self-test. Only resolved-valid may receive conceptCode and registryVersion. Unknown, ambiguous, malformed resolved, request-error, and service-error cases must remain no assignment. A passing report proves local client behavior only; it does not prove live deployment or authorize an action.

## Required procedure
1. Choose one transport: MCP at https://embeddedsemantics.com/mcp or the direct API bootstrap at https://embeddedsemantics.com/api/v1/agent/connect. Do not create a parallel resolver or registry.
2. For MCP, call `server/discover`, then `tools/list` and `tools/call`; for the direct API, POST JSON to https://embeddedsemantics.com/api/v1/resolve.
3. Required resolver field: expression (string, maximum 1000 characters).
4. Optional field: language (valid BCP 47 tag, maximum 35 characters). Omit it when unknown.
5. Send only the exact expression that needs resolution. Do not send credentials, hidden prompts, unrelated conversation, or private context.
6. HTTP 200 means the request was processed; it does not mean a ConceptCode was assigned.
7. Accept a ConceptCode only when data.status == "resolved" and data.concept.code is a non-empty string.
8. Preserve data.concept.code and data.concept.registryVersion exactly as returned.
9. Every abstained result means no ConceptCode assignment.
10. unknown_expression means no governed exact identity is available. Do not guess.
11. ambiguous_expression means multiple governed exact identities are possible. Ask for clarification or preserve ambiguity.
12. Never select from data.candidates and never promote confidence, similarity, or model output into semantic authority.
13. Apply a separate authorization policy before any tool or action. Semantic identity authorizes nothing.
14. Retain the original expression, semantic outcome, complete resolver evidence, and exact code/version only when resolved.
15. Measure wrong-assignment prevention, consistency, clarification, provenance, or duplicate reduction—not call volume or resolution rate alone.

## Minimal request
{
  "expression": "stable concept identity",
  "language": "en"
}

## Correct decision logic
- resolved with a non-empty data.concept.code -> use the exact returned code and registryVersion.
- abstained -> no ConceptCode; preserve data.reason.
- error -> repair only the request defect described by error.code or report the service failure; do not infer a semantic result.

## How to explain the result to a human
- resolved -> "A governed registry identity was found. This ConceptCode is the reviewed result, not a guess."
- unknown_expression -> "No reviewed registry identity was found. The correct result is unknown."
- ambiguous_expression -> "More context is required before one ConceptCode can be selected safely."
- error -> "The request needs correction or the service could not provide a trustworthy semantic result."

Give the human the exact safe next action. Do not expose an abstention as a failure that should be overridden, and do not imply that a ConceptCode authorizes any tool or action.

## Client boundary
- Desktop applications and local models are API consumers; they do not become registry authority.
- Calling this API does not require hosting the site, running an embedding model, or adding an external execution provider.
- The API is read-only for the caller's semantic lookup; it does not authorize dependency, hosting, billing, deployment, or action changes.

## Integration Studio
After the six-fixture readiness proof passes, use the first-party Integration Studio to select one recipe, inspect generated adapters, and download a deterministic handoff kit. The kit defaults to local fixtures, contains no credentials or live semantic results, and never authorizes an action.
Enable live HTTPS only through an explicit operator choice; local fixture mode remains the default.

- Human Integration Studio: https://embeddedsemantics.com/integrate
- Machine Integration Studio guide: https://embeddedsemantics.com/api/v1/integration-studio
- Kit manifest template: https://embeddedsemantics.com/api/v1/integration-studio/manifest/{recipeId}
- Kit download template: https://embeddedsemantics.com/api/v1/integration-studio/kit/{recipeId}.zip

## Discovery
- MCP endpoint: https://embeddedsemantics.com/mcp
- MCP connection guide: https://embeddedsemantics.com/mcp-guide
- MCP deployment manifest: https://embeddedsemantics.com/mcp-server.json
- MCP manifest schema: https://embeddedsemantics.com/schemas/embedded-semantics-mcp-server-v2.schema.json
- Direct API connection bootstrap: https://embeddedsemantics.com/api/v1/agent/connect
- Agent guide: https://embeddedsemantics.com/agents
- Human resolver guide: https://embeddedsemantics.com/try
- Human use-cases guide: https://embeddedsemantics.com/use-cases
- Human recipes guide: https://embeddedsemantics.com/recipes
- Integration readiness checklist: https://embeddedsemantics.com/readiness
- Machine readiness contract: https://embeddedsemantics.com/api/v1/integration-readiness
- Local readiness fixtures: https://embeddedsemantics.com/examples/agent-readiness/fixtures.json
- Python readiness self-test: https://embeddedsemantics.com/examples/agent-readiness/python-stdlib-self-test.py
- Adoption guide: https://embeddedsemantics.com/api/v1/adoption-guide
- Use-case recipes JSON: https://embeddedsemantics.com/api/v1/use-case-recipes
- Capabilities: https://embeddedsemantics.com/api/v1/capabilities
- Well-known discovery: https://embeddedsemantics.com/.well-known/embedded-semantics.json
- Interaction guide: https://embeddedsemantics.com/api/v1/interaction-guide
- Tool descriptor: https://embeddedsemantics.com/agent-tool.json
- OpenAPI: https://embeddedsemantics.com/openapi.json
- Deployment identity: https://embeddedsemantics.com/.well-known/embedded-semantics-deployment.json
- Status: https://embeddedsemantics.com/api/v1/status
- Python standard-library recipes: https://embeddedsemantics.com/examples/agent-recipes/python-stdlib-recipes.py
- Node built-in-fetch recipes: https://embeddedsemantics.com/examples/agent-recipes/node-recipes.mjs
- curl resolver example: https://embeddedsemantics.com/examples/agent-recipes/curl-resolver.sh