docs: front doors for node operators and publishers

[thiras]

Summary

The last PR of the persona restructure. It is stacked on #134, and its text describes #131 (Compose origin profile) and #132 (chart origin docs), so merge it after all of them.

• docs/node-operators.md. What a cache node is and the entry point on each deploy path. A miss is filled from other nodes and paid from the node's own pool (ADR 003). It also covers the on-chain stake and registration step (ADR 019) and the caveats of moving to self-hosted relays or discovery.
• docs/publishers.md.
  • Who a publisher is (ADR 002), with the CLI steps: decdn publish namespace create / assign / revoke, and decdn origin import.
  • The four services: origin, sponsord + onramp, iroh relay, iroh DNS server. Each comes with its group, playbook and the other paths it runs on.
  • How an origin differs from a cache node:
    • it serves only what its backend holds (ADR 002 § Retrieval by namespace);
    • it is recognised only once seated (ADR 011).
  • Relay allowlist and DNS caveats, and that decommissioning an origin leaves it seated.
• README opens on the two personas. AGENTS.md "What this repo is" describes the persona entry points. requirements.md and lifecycle.md gain the origin notes.

A fact-check pass against the ADRs and the code corrected one claim. The relay_foreign_namespaces gate depends on the node's backend, not on the namespace. That wording was also fixed in #133, #131 and #132.

Test plan

• make lint (markdownlint)
• make test-scripts and make lint-cloud-init on the full stack
• Every cited ADR anchor checked against the upstream headings

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new guides misdescribe PaymentPool spending and origin import behavior, and contain invalid role paths.

5 open findings

• Clarify deposit is a refill target, not a spending cap · New
• Fix role README paths to include ansible directory · New
• Document origin import limitations for S3 and HTTP backends · New
• Fix backend configuration link to the ansible role · New
• Fix role README links to include ansible directory · New

What changed in this PR

Adds persona-based documentation front doors for node operators and publishers.

Changes:

• Documents cache-node and publisher workflows across deployment paths.
• Clarifies origin lifecycle, relay, discovery, and on-chain requirements.
• Updates repository navigation and contributor guidance.

File	Description
README.md	Adds persona-based entry points.
AGENTS.md	Documents persona-specific deployment structure.
docs/​node-operators.md	Adds the cache-node operator guide.
docs/​publishers.md	Adds the publisher and origin guide.
docs/​requirements.md	Applies requirements to cache and origin nodes.
docs/​lifecycle.md	Documents origin decommissioning.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.