{
  "markdown": "# HX Eco-System\n\nAuthoritative repository for the clean-room HX Eco-System rebuild: a\n**17-server native-Linux AI ecosystem**, built one server at a time, each one\nvalidated and recorded before the next begins.\n\n> **Cornerstone first.** Understand the ecosystem and its configuration before\n> applying skills or the smoke-test model. Skills augment expertise. Validation\n> proves the architecture. Neither one defines the ecosystem.\n\n---\n\n## 1. Start here\n\n| You are | Read this |\n|---|---|\n| An agent working in this repo | `AGENTS.md` — the operating contract |\n| Building a server today | `docs/03-runbooks/RUN-SHEET.md` |\n| Looking for current state | `docs/00-control/hx-fleet.tsv` |\n| Deciding something | `docs/00-control/DECISIONS.md` |\n| Reading as a human | `human-html/` — generated, never authority |\n\n---\n\n## 2. Build order\n\nEach layer depends on the one before it. This is dependency sequencing, not\npermanent integration wiring.\n\n```mermaid\nflowchart LR\n    F[\"<b>Foundation</b><br/>HX-1\"]\n    I[\"<b>Inference</b><br/>HX-2 · HX-3 · HX-4 · HX-5\"]\n    S[\"<b>State &amp; retrieval</b><br/>HX-9 · HX-10\"]\n    C[\"<b>Routing &amp; MCP</b><br/>HX-6 · HX-15 · HX-7\"]\n    K[\"<b>Knowledge</b><br/>HX-16 · HX-17\"]\n    R[\"<b>RAG &amp; memory</b><br/>HX-11 · HX-13\"]\n    A[\"<b>Agents &amp; workflow</b><br/>HX-12 · HX-14\"]\n    U[\"<b>Interface</b><br/>HX-8\"]\n\n    F --> I --> S --> C --> K --> R --> A --> U\n```\n\nTwo things cut across every layer and are deliberately **not** drawn, because\ncross-cutting concerns make a diagram less readable rather than more:\n\n- **Governed skills** (`skills/`) advise on any component. They never decide.\n- **Validation** (`smoke-tests/`, run from HX-5 CentCom) proves any component.\n  It never becomes an architecture layer of its own.\n\n---\n\n## 3. Current state\n\n<!-- HX-FLEET:TABLE columns=id,ip,role,state -->\n| Server | IP | Assignment | State |\n|---|---|---|---|\n| HX-1 | `192.168.50.200` | Samba AD / DNS / Kerberos / NTP | **PASS** |\n| HX-2 | `192.168.50.202` | Qwen-X / Ollama | **PASS** |\n| HX-3 | `192.168.50.203` | Coder-X / Ollama | **PASS** |\n| HX-4 | `192.168.50.204` | Meta-X / GPT-OSS 20B + BGE-M3 + Nomic + BGE reranker | **NOT STARTED** |\n| HX-5 | `192.168.50.205` | CentCom / Ornith / DeepSeek Harness / dev-test | **NOT STARTED** |\n| HX-6 | `192.168.50.206` | OmniRoute | **NOT STARTED** |\n| HX-7 | `192.168.50.207` | NGINX dev/test only | **NOT STARTED** |\n| HX-8 | `192.168.50.208` | Open WebUI | **NOT STARTED** |\n| HX-9 | `192.168.50.209` | PostgreSQL + MCP / Redis + MCP | **NOT STARTED** |\n| HX-10 | `192.168.50.210` | Qdrant + Web UI + MCP | **NOT STARTED** |\n| HX-11 | `192.168.50.211` | LightRAG + MCP | **NOT STARTED** |\n| HX-12 | `192.168.50.212` | Deep Agents (LangChain) LOB agent factory | **NOT STARTED** |\n| HX-13 | `192.168.50.213` | Mem0 + assigned MCP | **NOT STARTED** |\n| HX-14 | `192.168.50.214` | n8n + MCP | **NOT STARTED** |\n| HX-15 | `192.168.50.215` | FastMCP shared/custom MCP development host | **NOT STARTED** |\n| HX-16 | `192.168.50.216` | Docling + Granite-Docling 258M + MCP | **NOT STARTED** |\n| HX-17 | `192.168.50.217` | Crawl4AI + MCP | **NOT STARTED** |\n<!-- /HX-FLEET:TABLE -->\n\nGenerated from `docs/00-control/hx-fleet.tsv`. Edit that file, then run\n`tools/hx-doc/hx-fleet`. Do not hand-edit the table.\n\n**Design readiness is not as-built completion.** A pinned version and a written\nrunbook mean the work is planned, not that it is running.\n\n---\n\n## 4. Foundational configuration\n\n| Item | HX baseline |\n|---|---|\n| LAN | `192.168.50.0/24` |\n| Gateway | `192.168.50.1` |\n| Infrastructure DNS | HX-1 |\n| AD domain | `hx.local.arpa` |\n| Kerberos realm | `HX.LOCAL.ARPA` |\n| Domain client pattern | SSSD / realmd / adcli |\n| Deployment | Native Ubuntu Linux + systemd |\n| Containers | Not used unless explicitly approved |\n| Normal UI access | Direct native application server and port |\n| NGINX | HX-7, development and test rendering only |\n\nHX-1 through HX-3 have current as-built evidence. Everything else is planned\nuntil verified during that server's own build.\n\n---\n\n## 5. Core rules\n\n- **KISS.** One server, validate it, record it, move on.\n- **Native.** Linux and systemd. No Docker, Podman or Kubernetes.\n- **Clean room.** Historical HX-Infrastructure artifacts are reference only and\n  do not establish current state.\n- **Package sources.** Application software comes from PyPI, npm, a GitHub\n  release, an upstream source tarball, a direct binary, or Hugging Face. The\n  Ubuntu archive is used only for the NVIDIA driver and for build toolchains\n  and library headers. Never Snap.\n- **Companion services.** A product's own MCP server and native Web UI are part\n  of that application's base build. HX-15 FastMCP is a shared development host,\n  not a prerequisite for any of them.\n- **Retrieval plane.** BGE-M3 primary at 1024 dimensions, Nomic Embed Text v1.5\n  alternate at 768, and the BGE reranker — all on HX-4. Never mix embedding\n  identities in one Qdrant collection; a model change means a new collection\n  and re-embedding.\n- **Granite-Docling** stays with Docling on HX-16, CPU-first for base validation.\n- **NGINX** is HX-7 development and test only, never the ecosystem front door.\n- **Base before integration.** Permanent routes, production schemas and\n  collections, agent bindings, RAG ingestion, workflows and end-to-end wiring\n  all come after standalone base closure.\n\n---\n\n## 6. Building a server\n\nEvery server follows the same six steps. Full detail, including what will stop\nyou on each host, is in `docs/03-runbooks/RUN-SHEET.md`.\n\n```bash\ntools/hx-doc/hx-preflight                        # from anywhere, before build day\n\ncd docs/03-runbooks\n./common/01-base-admin-network-updates.sh hx-9   # reboots\n./common/02-domain-nvidia.sh hx-9                # reboots\n./common/10-postgresql.sh hx-9                   # the application\n```\n\nOne implementation of each block lives in `docs/03-runbooks/common/`, with\nfive-line per-server wrappers. Every block refuses to run on the wrong host.\nVersions are pinned in `common/hx-base.env` and audited by\n`tools/hx-doc/hx-version-pins`.\n\nValidation is two questions, everywhere: **does the service start, and does it\nsurvive a reboot.**\n\n---\n\n## 7. Two roadmaps — build first, prove second\n\n```text\nBASE IMPLEMENTATION ROADMAP     what gets built, in what dependency order\n            |\nSMOKE-TEST ROADMAP              what proof runs next, on which prior evidence\n            |\nCOMPONENT SMOKE AUTHORITY       exactly how each known-answer test is run\n```\n\n- Build order: `docs/00-control/HX-ECO-SYSTEM-BASE-IMPLEMENTATION-PRIORITY.md`\n- Proof order: `docs/00-control/HX-ECO-SYSTEM-SMOKE-TEST-ROADMAP.md`\n- Exact procedures: `smoke-tests/`\n\nThe proof roadmap uses **cumulative evidence with minimal live coupling**. A\ndownstream test reuses prior PASS evidence and creates only the smallest\ntemporary integration needed to prove its own contract. Temporary wiring is\nremoved before closure.\n\nService health is never enough. A known-answer test is required, cleanup is\npart of PASS, and reviewed evidence plus reboot persistence closes the loop.\n\n---\n\n## 8. Governed skills\n\n`skills/` is the canonical HX library of reusable agent expertise. A skill may\nimprove planning, native installation and configuration reasoning,\ntroubleshooting, upgrades and validation preparation. It does **not** replace\narchitecture, runbooks, or acceptance criteria.\n\n```text\nHX context -> component runbook -> HX skill wrapper -> current vendor guidance\n           -> reconcile with HX decisions -> execute from HX authority\n```\n\nApproved wrappers cover Qdrant, LightRAG, PostgreSQL, Redis, Mem0, Docling and\nCrawl4AI. Each pins the exact upstream commit it was reviewed against, and\n`tools/hx-doc/hx-upstream-drift` reports when one moves.\n\nSkill approval is guidance only. It never changes the build state of the\nassigned server.\n\nAuthorities: `skills/README.md`, `skills/SKILL-GOVERNANCE.md`,\n`skills/SKILL-REGISTRY.md`, `skills/AGENTS.md`.\n\nSkills never contain credentials of any kind.\n\n---\n\n## 9. Repository tooling\n\nRules kept only in prose drift. These enforce them, and CI runs all of them on\nevery change. Python 3 standard library only, no dependencies.\n\n| Command | Enforces |\n|---|---|\n| `hx-preflight` | every pinned artifact is still fetchable, checked from anywhere |\n| `hx-fleet` | every fleet table and the runbook IP map comes from the TSV |\n| `hx-proof` | every proof step and edge comes from the TSV, and the DAG is valid |\n| `hx-render-html` | every mirror matches its Markdown source |\n| `hx-doc-check` | links resolve, vocabulary is defined, filenames are stable |\n| `hx-version-pins` | pins are current, and no application comes from apt or Snap |\n| `hx-upstream-drift` | the registry's reviewed commits are still current |\n| `hx-record-check` | server records follow the template; open gaps stay visible |\n| `hx-smoke-lint` | smoke authorities carry every required section |\n| `hx-new-server` | a new server's runbook and record start complete |\n| `hx-doc-supersede` | the archive procedure runs the same way every time |\n\n```bash\ntools/hx-doc/hx-doc-check          # before committing\ntools/hx-doc/hx-render-html        # after editing any Markdown\n```\n\n`human-html/**` is **generated output**. Edit the Markdown and re-render; never\nedit a mirror by hand. Detail in `tools/hx-doc/README.md`.\n\nCI also runs shellcheck, a CRLF and executable-bit check, a Python compile, and\na secret scan, and CodeRabbit reviews every pull request against the rules in\n`.coderabbit.yaml`. A weekly workflow reports version drift as a single issue.\n\n---\n\n## 10. Authoritative surfaces\n\n| Path | Status |\n|---|---|\n| `docs/00-control/hx-fleet.tsv` | single source of truth for the fleet |\n| `docs/**/*.md` | current control, architecture, standards, records, runbooks |\n| `docs/03-runbooks/**/*.sh` | approved execution artifacts |\n| `smoke-tests/*.md` | component acceptance authorities, validation only |\n| `skills/**` | governed agent expertise, subordinate to the above |\n| `tools/**` | repository tooling |\n| `human-html/**` | generated human view, never execution authority |\n| `archive/**` | superseded history, never current authority |\n\n---\n\n## 11. Reading order for agents\n\nLearn the ecosystem before the skills, and the skills before the validation:\n\n1. `README.md`\n2. `docs/00-control/CURRENT-STATE.md` and `docs/00-control/BUILD-STATE.md`\n3. `docs/00-control/DECISIONS.md`\n4. `docs/01-architecture/ARCHITECTURE-ORIENTATION.md`\n5. The relevant server record, runbook, and application standard\n6. If a governed skill exists: `skills/SKILL-GOVERNANCE.md`, then the wrapper\n7. **Only when validating:** the smoke-test roadmap, the operating model, then\n   the exact `smoke-tests/` authority\n8. If using the runner: `tools/hx-smoke-runner/AGENTS.md`\n\nBefore validating anything, an agent must be able to state the component's\nowner server, target IP, role, current state, applicable foundation rules,\ndependencies, BASE PASS boundary, and required prior PASS evidence. If it\ncannot, it is not ready to run the test.\n\n`CLAUDE.md` points back to `AGENTS.md` so agent instructions cannot drift apart.\n\n---\n\n## 12. Document lifecycle\n\nActive documents use stable, unversioned filenames. Version, date and status\nlive inside the document.\n\nTo supersede one:\n\n```bash\ntools/hx-doc/hx-doc-supersede docs/00-control/DECISIONS.md --suffix pre-d021\n# edit the active file, then:\ntools/hx-doc/hx-render-html && tools/hx-doc/hx-doc-check\n```\n\nThat archives the prior copy and its mirror under `archive/YYYY-MM-DD/`, leaves\nthe active file in place to edit, and leaves exactly one active version.\n",
  "bytes": 11647,
  "sha": "9b1120cf5bee5f65d2b76c4b7d1e74e15ee23350301766e137617e4bdf697301",
  "repo_slug": "hx-infratstructure/hx-eco-system",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_hx_infratstructure_hx_eco_system_openwik_15223f14/readme"
}