docs: add Resource-Footprint page with real numbers from first VPS deploy
Document the disk/RAM/CPU footprint of a live deployment so anyone
sizing a VPS for DECNET can see what to expect. Numbers are from the
first Contabo deploy: 4.5 GiB disk, 2.1 GiB RAM, 0.03 load average,
12 containers, 12 workers, ~80 attackers in the first hour.
Adds a "what scales with topology size" breakdown so operators can
project from these numbers to their own target deployment, and a
sizing-floor recommendation per deployment shape (UNIHOST small,
UNIHOST medium, SWARM master, SWARM agent).
Linked from the User docs section of the sidebar between
Tailscale-Global-Deployment and MazeNET.
Document the realism content engine, the orchestrator service collapse,
and every public surface change from the migration on dev.
Page-level changes:
- Realism.md (new) — operator walkthrough of the realism library:
ContentClass taxonomy, persona pools (topology vs global), diurnal
gating, edit-in-place, LLM enrichment with circuit breaker, and 3%
canary cultivation. Configuration table and CLI surface.
- Module-Reference-Core.md — new "decnet/realism/" section covering
taxonomy / planner / naming / bodies / personas / LLM backend /
prompts. Notes the env-var rename.
- Module-Reference-Workers.md — new "Orchestrator" section covering
the unified worker, action-kind weights, drivers (ActivityDriver
ABC, plant_file/read_file contract, _run_edit), and the email
delivery surface that stayed put (events / threads / scheduler).
- Service-Bus.md — fix orchestrator topic table: emailgen producer
attribution is gone (orchestrator owns email now), system.emailgen.*
topics removed.
- CLI-Reference.md — new "decnet orchestrate" and "decnet realism
import-personas" sections plus DECNET_REALISM_* / DECNET_CANARY_*
rows in the env summary.
- Environment-Variables.md — new "Realism content engine" and
"Canary worker" sections; starter .env.local entries appended.
- Systemd-Setup.md — bundled decnet-orchestrator.service template
with the realism env block; explicit note that decnet-emailgen
is gone post-migration.
- Design-Overview.md — Orchestrator + Canary rows added to the
microservice table; Realism cross-link in the Related Pages list.
- Roadmap-and-Known-Debt.md — moved orchestrator-fake-files and
emailgen-twin-worker entries to "Recently closed" with a pointer
to the migration history.
- Home.md, _Sidebar.md — Realism added to the user-docs nav.
docs(wiki): Identity-Resolution page + identity.* topics in Service-Bus
Documents the observation/identity/campaign three-level hierarchy, the
read-only API surface, the deferred clusterer worker, and how to test
the substrate. Companion to development/IDENTITY_RESOLUTION.md in the
main repo.
Service-Bus.md gains the three identity.* topic rows (reserved for the
future clusterer); sidebar links Identity-Resolution under Developer
docs alongside Campaign-Clustering.
docs(wiki): Campaign-Clustering page + sidebar link
Documents the pre-implementation test infrastructure: UKC vocabulary,
synthetic campaign factory + DSL, metric harness, fixture layout, and
how to run the suite. Algorithm itself isn't built yet — the simulator
ships first per the design doc.
Playbook for taking DECNET into the wild on geographically dispersed
VPSes with management bound to tailscale0 and decoys on the public NIC.
Covers bind cheat sheet, ACL recipe, firewall belt-and-suspenders,
SWARM + UNIHOST walkthroughs, live-QA hardening checklist, and
troubleshooting.
Documents the host-local UNIX-socket pub/sub transport: architecture,
topic hierarchy, env vars, code examples (publish/subscribe +
get_app_bus for the API), at-most-once delivery semantics, the
live-topology-mutation worked example, testing helpers, and
troubleshooting. Linked from the user-docs section of the sidebar
between Systemd setup and Logging.
docs: document swarm/agent/updater APIs and add PKI-and-mTLS reference
- Module-Reference-Workers: new sections for decnet/swarm/, decnet/agent/,
and decnet/updater/ covering exported symbols, FastAPI routes, uvicorn
launcher flags, and the executor seams the test suite monkeypatches.
- PKI-and-mTLS: standalone developer page covering CA generation, leaf
issuance, SSLContext wiring (client + server), the VERIFY_X509_STRICT
workaround for Python 3.13, the RFC 5425 log pipeline's reuse of the
same CA, and the currently-unenforced CN/role-separation gap.
- Sidebar: link the new PKI page from the Developer docs section.
docs(swarm): add SWARM Mode page and cross-link from Deployment Modes
Comprehensive walkthrough for the newly-landed SWARM control plane:
- Architecture diagram (master: swarmctl/listener/ingester/api; worker:
agent/forwarder) with ports cheat sheet
- Step-by-step setup (CA bootstrap, enrollment, bundle shipment, agent +
forwarder startup, check, first swarm deploy)
- Full command reference for swarmctl, listener, agent, forwarder, and
the swarm enroll/list/check/decommission subcommands
- Log-pipeline end-to-end story (RFC 5424 on worker → RFC 5425 mTLS on
6514 → master.json → ingester → dashboard), including tcpdump-based
plaintext-leak check and source_worker provenance note
- Operational concerns: master crash resume (no dup/loss), worker crash,
CA rotation, cert rotation, teardown
- Security posture summary
- Known limitations (get_host_ip master-side bug, no web UI yet,
round-robin only, single master)
- Troubleshooting matrix
Deployment-Modes: trimmed the old 'swarm is not implemented, drive it
from Ansible' section and replaced with a link to the new page.
_Sidebar: added SWARM-Mode under User docs.
