Use case: researcher wiki maintainer

Synced from agent-operator/docs/documentation/usecases.researcher-wiki-maintainer.md. The repository is the source of truth.

This is the target composition for M2: Email Paper Research.

An example composition over the Agent Operator primitives: an agent that watches an email inbox, ingests emailed research papers into an organization’s wiki, and replies in-thread with a source-traceable commit. Email is its channel; the wiki and source-ingest skills are its tools. A different composition would swap the channel (GitHub notifications, Signal) or the tools while reusing the same workspace, secret/config exposure, catalog, and delegation primitives.

Follow the quick start first to stand up the cluster, an organization, and the researcher agent’s workspace. This page covers what the researcher composition adds on top.

What it needs

Beyond the operator and cluster prerequisites, this composition needs:

• a writable Git wiki repository with Git LFS enabled — the organization’s wiki repository, which the agent commits to;
• a JMAP mailbox for the agent (the local environment supplies Stalwart); and
• credentials for the model the researcher agent selects.

Credentials

The operator exposes referenced Secrets/ConfigMaps by name without inspecting them (quick start §4); the keys inside are this composition’s contract, defined here. Create these Secrets in the agent-researcher namespace — via your cluster’s secret manager in production, or ignored 0600 files loaded with kubectl for local development.

The mail skill and xin CLI use this email.env contract:

XIN_BASE_URL=http://stalwart.agent-system.svc.cluster.local:8080
XIN_BASIC_USER=researcher@outfitter.test
XIN_BASIC_PASS=REPLACE_ME

Cleartext HTTP is permitted only inside the isolated Stalwart demo. Use HTTPS for a real mailbox.

Create the email Secret:

kubectl -n agent-researcher create secret generic \
  researcher-email \
  --from-env-file=email.env

Create the model Secret with the environment variable expected by the selected model provider:

kubectl -n agent-researcher create secret generic \
  researcher-model \
  --from-env-file=model.env

For private wiki or catalog repositories, create the SSH Secret and known-hosts entry from local files:

kubectl -n agent-researcher create secret generic \
  researcher-ssh \
  --type=kubernetes.io/ssh-auth \
  --from-file=ssh-privatekey=./id_ed25519 \
  --from-file=known_hosts=./known_hosts

Remove the temporary credential files when they are no longer needed. Bootstrap Secret volumes are mounted read-only. The agent is the administrator of its namespace workspace and can manage its namespaced Secrets, but cannot access Secrets in another namespace.

Once these exist, CredentialsReady and then Ready become true (see quick start §5).

Email a paper

Email is this composition’s channel — the way the researcher receives work. Send one message to the configured agent address with exactly one PDF attachment of at most 25 MiB. The email maps to the agent’s configured default organization (delivered as runtime config, not a CRD field).

The agent will:

1. receive the message while it is in INBOX;
2. clone the organization’s wiki into storage it manages in its namespace workspace;
3. run the selected Dotagents agent through Outfitter and Pi;
4. preserve the PDF under wiki/sources/ using Git LFS;
5. extract content.md with Docling and add a source note;
6. update concepts, the wiki index, and the append-only log;
7. list linked papers to explore next without downloading them;
8. create one local Git commit; and
9. reply in the original email thread with its summary and commit SHA; and
10. move the original from INBOX to Processed, which is the server-side reply-tracking state.

Today the agent does not push the commit, and research traversal is limited to the emailed seed paper; future recursive research has a hard maximum depth of five.