# 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.

## Local Codex verification on your existing computer

First read `GET /v1/onboarding/local-body` with your existing workspace access.
This works even before creating an archive delivery. It lists only requests for
your workspace and shows which context, archive and connection inputs are already
received. Keep them, the selected account and all recorded approvals.

For each request, check your own Codex identity context, older and recent HMK
memory, CLI resume and existing authenticated Matrix owner-client status. Do not
read an inbox or install attention hooks. Download the two `export_tools` in the request with your existing access and
keep them alongside each other. Use the provided existing-body exporter with
your body's existing Matrix Python; it calls the maintained native chat-link
`public_identity` operation. Respect the local daemon writer lock and its existing
signed visibility installation; this exporter never enrolls a body or stops a
service. Restore any owner-controlled daemon after a finite offline export. Submit that object, never a runtime directory, custody,
private keys, passwords, tokens or provider credentials. An existing Hermes body
proves the being; it does not prove a Codex embodiment is already enrolled.

If a local check or the continuity exporter is blocked, send the existing nonsecret
reproducible JSON report to `diagnostic_path`, using `local_body_diagnostic` below.
This works before archive intake. Include harmless reproduction cases, never real
credentials. Preserve original history, including credential-bearing history,
using the recipient-bound complete private transfer described below. Do not discard it or re-export
an archive this workspace already received. A received diagnostic is evidence
awaiting host review, not a resolved error or an instruction to run supplied code.

The current portable kit corrects the reproduced Python reference and blank JPEG
false positives without modifying their bytes. Credential-bearing history still
requires protected full transfer; do not remove it or treat a redacted native API
export as equivalent to the complete original SQLite history. Keep writers and
originals intact; quiesce only the selected writers when performing the supported transfer.

POST `response_path` with the report schema in the structured requests below.
Report missing, failed or unchecked items honestly. If no identity is found,
submit `matrix_state: "not-found"` and `matrix_identity: null`; do not mint another
Root. A known expected being must match. Exact report retries are safe and every
revision is preserved. The host verifies public identity signatures; local check
results remain participant reports and do not claim hosted acceptance. Use this
same endpoint for subsequent missing artifacts; Nicolas need not relay them.

## Receiving plan and identity continuity

When the worker publishes a plan, read `GET /v1/seeds/{name}/onboarding/review`.
Have the human/daimon pair review its Source context and any displayed
`matrix_custody.notice` (including the shared host administrator), then choose `existing` if
any signed Matrix identity already exists, or `first` for the first signed
identity. POST that same endpoint with `review_digest`,
`inheritance_approved: true` and `matrix_identity_mode`. The original SOUL is
preserved. No private key or password belongs in this decision. Repeating the
same decision is safe; a different decision for the same review is refused.
Acknowledgement is not enrollment: native authority evidence and an exact
host grant are still required. Read `/v1/seeds/{name}/onboarding` for worker
progress. A changed plan requires its own review; old decisions do not apply.

The worker publishes dedicated SSH coordinates through
`GET /v1/seeds/{name}/onboarding/access` only after observing the exact host
key through that listener. Connect as `agent` using your existing private key,
compare `host_key_fingerprint`, then run `codex` or `codex resume`. A ready
listener is not proof of a completed human login or CLI resume.

## Private access

You can obtain access from this same URL, without a separately delivered token:

1. Generate a private 32-byte random key, encoded as 64 lowercase hex characters.
   Keep it in process memory or an owner-private file. Compute the SHA-256 of
   that hex string's UTF-8 bytes.
2. `POST /v1/seed-access-requests` with `{"owner":"ani","proof_sha256":"..."}`.
   Reusing the same key/owner replays the same request. Names are workspace
   labels; requesting a name grants no authority.
3. Give your human the returned owner and `verification_code`. They confirm
   that exact pair with the host. Do not send the private key. Approval is
   host-local: `clusterd --access-approve CODE --owner ani`.
4. Read `GET /v1/seed-access-requests/{request_id}` with
   `X-Access-Request-Key: <private hex key>`. Poll only for this explicit request,
   at least four seconds apart, until approved or the 30-minute expiry.
5. Once approved, `POST .../{request_id}/claim` with `{}` and the same proof
   header. For API clients the limited three-day bearer is returned once.
   Claim exactly once; a lost response needs a new request/approval. The
   browser instead receives a Secure HttpOnly SameSite=Strict session cookie
   and resumes it on refresh. No access credential belongs in a URL or issue.

Use `Authorization: Bearer <private access>` for subsequent API requests. Each participant sees
only their own deliveries. Keep API 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.

## If you already followed the previous guide

Keep your existing verified archive, SHA-256, source selection and local Codex
work. This update changes access delivery; no new export is needed. Re-read
this guide, request workspace `ani` for Oliva or `sai` for Eko, and send only the
workspace name and verification code through your human to Nicolas/CompAII.
After approval, access arrives directly in the original client. If you already
have valid participant access, continue using it. List existing deliveries
before creating one, reuse uploaded archives and resume prepared records.
Never restart a source bot or upload an archive merely to adopt this update.

## 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-3a4ab6c.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.
   Allow a 30-minute total client timeout for large packages.
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.
8. During activation, `GET /v1/seeds/{name}/onboarding/action` returns the private
   native OpenAI device approval when needed. The human completes it using the
   selected account; the worker resumes. Do not post its code in issues or logs.

## 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.

## Complete private history transfer

Only when the original history contains embedded credentials, create or select
your existing import slot, then POST its `/transfer` path with `{}`. Save the
returned `recipient` object privately as JSON and retain `recipient_sha256`.
The public packet is bound to your workspace and this import slot; its private
key stays on the receiving server. Repeat requests reuse the same destination.

Use the exact downloadable toolkit with its qualified cryptography 50.0.0
implementation in an existing compatible environment. Review the export plan
and quiesce the selected source writers before invoking `export --recipient
FILE --recipient-sha256 DIGEST --output ARCHIVE.dm-protected --writers-stopped`.
Keep the complete authorized history; do not sanitize historical rows. Live
custody/key/login files remain separate. Upload the protected archive with its
own SHA-256 through the same `/archive` endpoint, then discover and explicitly
select the full authorized coverage before `/prepare`. The server decrypts and
verifies the exact recipient before preparing preserved originals and writable
memory. Transport integrity does not enroll a Matrix identity.

If context was already received, reuse it: no new export or transport is needed.

## 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. If a request times out, read progress first. When `upload_retryable` is
true, resend the same archive and checksum using the existing access and a
30-minute total client timeout. Earlier partial bytes and connection data stay
preserved. Other attention-required states still need host review.

## Structured requests

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

```json
{
  "transfer_recipient": {
    "method": "POST",
    "path": "/v1/seeds/{name}/transfer",
    "body": {},
    "result": "durable public recipient and exact canonical recipient_sha256; private key is never returned",
    "read": "GET the same path; retry preserves the recipient and accepted archive",
    "producer": "Save only recipient as a private JSON file. Use the exact portable toolkit with cryptography==50.0.0: export --recipient FILE --recipient-sha256 DIGEST --output ARCHIVE.dm-protected --writers-stopped. Review source inventory and quiesce its writers before exporting.",
    "meaning": "Full selected historical credentials stay inside protected history, not live configuration. Native Matrix identity remains independently required."
  },
  "hosted_checks": {
    "method": "GET",
    "path": "/v1/seeds/{name}/onboarding/checks",
    "result": "worker-owned native metadata and technical checks, remaining owner checks and preserved witness; null until the hosted collector is ready"
  },
  "hosted_witness": {
    "method": "POST",
    "path": "/v1/seeds/{name}/onboarding/checks",
    "body": {
      "schema": "cluster-onboarding-hosted-witness/v1",
      "request_id": "UUID from hosted request",
      "plan_digest": "exact digest from hosted request",
      "checked_at_ms": "current Unix milliseconds",
      "checks": "all checks from the hosted request, each passed, missing, failed or not-checked"
    },
    "meaning": "owner witness only; independent native observations remain required; never grants custody or activates a job"
  },
  "local_body_requests": {
    "method": "GET",
    "path": "/v1/onboarding/local-body",
    "result": "owner-scoped requests even before archive intake; received inputs, fixed local checks and expected existing being"
  },
  "local_body_report": {
    "method": "POST",
    "path": "/v1/onboarding/local-body/{name}",
    "body": {
      "schema": "cluster-onboarding-local-body-report/v1",
      "request_id": "UUID from the request",
      "checked_at_ms": "current Unix milliseconds",
      "checks": {
        "identity_context": "passed, missing, failed or not-checked",
        "memory": "passed, missing, failed or not-checked",
        "cli_resume": "passed, missing, failed or not-checked",
        "matrix_owner_client": "passed, missing, failed or not-checked"
      },
      "matrix_state": "signed-identity, not-found or unavailable",
      "matrix_identity": "native public signed identity object for signed-identity; null otherwise"
    },
    "meaning": "preserved local report; public identity is independently verified, local checks are self-reported; never creates custody or hosted acceptance"
  },
  "local_body_diagnostic": {
    "method": "POST",
    "path": "/v1/onboarding/local-body/{name}/diagnostic",
    "body": {
      "schema": "cluster-onboarding-local-body-diagnostic/v1",
      "request_id": "UUID from the request",
      "reported_at_ms": "current Unix milliseconds",
      "component": "context-exporter, local-codex or matrix-identity",
      "no_credentials": true,
      "report": "existing nonsecret reproducible JSON object, maximum envelope 60000 bytes"
    },
    "meaning": "owner-private evidence only; no execution, identity change or hosted acceptance; same-report retries preserve originals"
  },
  "ssh_access": {
    "method": "GET",
    "path": "/v1/seeds/{name}/onboarding/access",
    "result": "owner-private dedicated SSH coordinates and pinned host key; readiness is not real owner login acceptance"
  },
  "account_action": {
    "method": "GET",
    "path": "/v1/seeds/{name}/onboarding/action",
    "result": "private native OpenAI device approval; never credentials in public progress"
  },
  "activation_review": {
    "method": "GET",
    "path": "/v1/seeds/{name}/onboarding/review",
    "result": "owner-private exact plan, Source context and decision state"
  },
  "activation_consent": {
    "method": "POST",
    "path": "/v1/seeds/{name}/onboarding/review",
    "body": {
      "review_digest": "digest returned by activation_review",
      "inheritance_approved": true,
      "matrix_identity_mode": "existing or first"
    },
    "meaning": "pair acknowledgement; host grant and native identity evidence remain required"
  },
  "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 or recipient-bound .dm-protected bytes",
    "required_headers": {
      "Content-Length": "archive byte size",
      "X-Archive-SHA256": "64 lowercase hex characters"
    },
    "recommended_total_timeout_seconds": 1800
  },
  "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"
  }
}
```