# Daimon Matrix — private Cluster intake

This is the agent representation of the same human onboarding URL.
Use `Accept: text/markdown` or `?format=markdown`; use `Accept: application/json`
or `?format=json` for the structured contract and generated intake OpenAPI.
All endpoint paths below are relative to the human-selected HTTPS origin.

## What this service does now

Deliver and verify a portable ZIP/TGZ, preserve the original identity, memory,
skills and histories with provenance, prepare separate writable context, and
collect private bot/SSH connection data. Imports continue established beings;
new beings start with an initial SOUL and explicitly empty history.

`prepared` is context preparation. It does not mean an active or signed body.
Automatic runtime activation and the first bot welcome are not shipped yet.
Native HMK acceptance, canonical enrollment, SSH, provider login and the single
Telegram consumer still require actual receiving acceptance by the host.

## Private access

Your human or host supplies a limited participant access token privately.
Use `Authorization: Bearer <private access>` for the API. Each participant sees
only their own deliveries. Keep access and connection values in private files
or process memory; do not paste them into public issues, logs or the archive.
This entrypoint is public metadata and contains no participant records.

## Continue an existing being

1. Reuse your already verified packet and checksum. Do not rebuild local context
   or re-export solely because this page changed. If needed, the portable tools
   at `/downloads/being-seed-tools-4d4ccd5.tgz` need only Python 3.11+ and support
   Hermes, Codex and selected mixed sources.
2. `POST /v1/seeds`, with a stable UUID `Idempotency-Key` and JSON:
   `{"name":"eko","label":"Eko","mode":"import","browser":true}`.
   The environment ID is a presentation/storage label, never identity authority.
3. `POST /v1/seeds/eko/archive`: raw archive bytes, its exact `Content-Length`,
   `Content-Type: application/octet-stream` and `X-Archive-SHA256`.
   The limit is 512 MiB compressed and 5 GiB expanded; chunked upload is refused.
4. `GET /v1/seeds/eko/selection`. Review the returned identity SOUL, memory stores
   and historical skills against the human-authorized source selection. Preserve
   the returned schema and being label. Set `memory_coverage` to `owner-selected`
   for chosen/partial memory, or `complete-authorized` for the actually complete
   authorized corpus. Select one own SOUL; do not substitute Source's autobiography.
5. `POST /v1/seeds/eko/prepare` with `{"selection": <reviewed object>}`.
   Originals and history remain preserved; source scripts are not executed.
6. `POST /v1/seeds/eko/connections` with the private `telegram_bot_token`, numeric
   `telegram_chat_id`, optional numeric `telegram_topic_id`, and `ssh_public_key`.
   Private keys and harness/provider authentication do not belong in the seed.
   For a direct conversation, the human first opens the chosen bot and sends
   `/start`. One bot has one intended ingress consumer.
7. `GET /v1/seeds` returns redacted owner progress. `telegram`/`ssh` data-supplied
   states are distinct from accepted connections. Report observed preparation
   and pending runtime checks accurately.

## Begin a new being

Create with `mode: "new"`, a name/label, optional browser flag and the human's
initial `soul`. Then prepare with `{"selection":null}`. The service makes and
receives the same standard archive; memory coverage is `empty-new`. Continue
with the separate connection step and actual receiving acceptance.

## Retries and recovery

Reuse the creation UUID with the same specification. If an archive is already
uploaded, discover that preserved archive instead of uploading again. Exact
preparation retries return the preserved result and retain later receiving
writes. A failed/partial operation needs host attention, not deletion or overwrite.
If a request times out, read progress before deciding what to repeat.

## Structured requests

Fetch `?format=json` for the generated OpenAPI subset and full metadata.

```json
{
  "create": {
    "method": "POST",
    "path": "/v1/seeds",
    "required_headers": {
      "Idempotency-Key": "UUID"
    },
    "body": {
      "name": "lowercase environment ID",
      "label": "daimon name",
      "mode": "import or new",
      "browser": "optional boolean",
      "soul": "required initial SOUL only for new"
    }
  },
  "upload": {
    "method": "POST",
    "path": "/v1/seeds/{name}/archive",
    "body": "raw ZIP/TGZ bytes",
    "required_headers": {
      "Content-Length": "archive byte size",
      "X-Archive-SHA256": "64 lowercase hex characters"
    }
  },
  "selection": {
    "method": "GET",
    "path": "/v1/seeds/{name}/selection",
    "result": "private verified candidates"
  },
  "prepare": {
    "method": "POST",
    "path": "/v1/seeds/{name}/prepare",
    "body": {
      "selection": "reviewed selection object; null for new"
    }
  },
  "connections": {
    "method": "POST",
    "path": "/v1/seeds/{name}/connections",
    "body_fields": {
      "telegram_bot_token": "private bot token",
      "telegram_chat_id": "nonzero integer",
      "telegram_topic_id": "optional nonzero integer",
      "ssh_public_key": "public key only"
    }
  },
  "progress": {
    "method": "GET",
    "path": "/v1/seeds",
    "result": "owner-scoped paginated progress"
  }
}
```