From 492045dcb4af1bb15cb14e3f0949ccca0aa37f44 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 29 Jun 2026 14:14:38 +0100 Subject: [PATCH] revert(readme): restore canonical README.adoc; remove runaway .md conversion The estate-wide 'convert README.adoc -> Markdown' pass over-applied the narrow boj-server/hyperpolymath .md rule to every repo. AsciiDoc is canonical here; restore README.adoc and remove README.md (clean revert). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.adoc | 141 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 150 ---------------------------------------------------- 2 files changed, 141 insertions(+), 150 deletions(-) create mode 100644 README.adoc delete mode 100644 README.md diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..517b5abf --- /dev/null +++ b/README.adoc @@ -0,0 +1,141 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) += AmbientOps + +image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] +image:https://api.thegreenwebfoundation.org/greencheckimage/jewell.nexus[Green Hosting,link="https://www.thegreenwebfoundation.org/green-web-check/?url=jewell.nexus"] + +:toc: +:toclevels: 3 +:icons: font +:source-highlighter: rouge + +AmbientOps is a hospital-model operations framework providing **trustworthy system help** without fearware, nagware, or scammy "optimizers". It is organised as a **hybrid monorepo**: core hospital departments live here, external tools stay as satellites. + +== Quick Start + +[source,bash] +---- +# Build everything (requires just, cargo, mix, deno) +just build-all + +# Run all tests +just test-all + +# Build Rust components only +cargo build --workspace + +# Run hardware scan with contract-conformant output +cargo run -p hardware-crash-team -- scan --envelope + +# Generate remediation plan +cargo run -p hardware-crash-team -- plan 01:00.0 --procedure + +# Emergency room with envelope output +cd emergency-room && v run src/ trigger --envelope + +# Generate system weather +cd observatory && mix sysobs weather --output /tmp/ambientops/weather.json + +# Run end-to-end demo +./scripts/demo-flow.sh --build +---- + +== Component Status + +[cols="1,1,1,1"] +|=== +| Component | Language | Tests | Maturity + +| contracts | JSON+Deno | 13 steps | 80% +| contracts-rust | Rust | 7 | 80% +| observatory | Elixir | 87 | 85% +| emergency-room | V | 9 (3 files) | 75% +| records/referrals | Elixir | 8 | 65% +| hardware-crash-team | Rust | 27 | 75% +| clinician | Rust | 16 | 55% +| composer | Gleam (planned) | 0 | 10% +|=== + +== The Hospital Model + +AmbientOps presents system tooling as four "departments": + +* **Ward** — System Weather + gentle ambient guidance (`observatory/`) +* **Emergency Room** — Panic-safe intake with one-click stabilization (`emergency-room/`) +* **Operating Room** — Planned procedures: Scan → Plan → Apply → Undo → Receipt (`clinician/`, `hardware-crash-team/`, `composer/`) +* **Records** — Receipts, undo tokens, and referrals (`records/`) + +**Data flow:** Evidence Envelope → Procedure Plan → Receipt → System Weather + +See `docs/HOSPITAL_MODEL.adoc` for the full model. + +== Directory Structure + +[source] +---- +ambientops/ +├── clinician/ (Rust, ~4400 LOC) — AI-assisted sysadmin [from personal-sysadmin] +├── emergency-room/ (V, ~1800 LOC) — Panic-safe intake [from emergency-button] +├── hardware-crash-team/ (Rust, ~700 LOC) — PCI zombie detection & remediation +├── observatory/ (Elixir, ~600 LOC)— Metrics, weather, bundle ingestion +├── contracts/ (JSON+Deno) — 8 JSON schemas + validators +├── contracts-rust/ (Rust) — Serde types matching JSON schemas +├── records/referrals/ (Elixir, ~400 LOC)— Multi-platform bug reporting MCP +├── composer/ (Gleam, stubs) — Orchestration engine +├── scripts/ — Demo and utility scripts +├── docs/ — Documentation +├── Cargo.toml — Rust workspace root +└── .machine_readable/ — .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/ECOSYSTEM.a2ml, .machine_readable/6a2/META.a2ml +---- + +== Contract Schemas + +The `contracts/` directory contains 8 JSON schemas that define the inter-component data format: + +[cols="1,2"] +|=== +| Schema | Purpose + +| `evidence-envelope` | A&E intake / scan output with artifacts and findings +| `procedure-plan` | Operating Theatre steps with risk and reversibility +| `receipt` | Execution result with undo bundle and evidence +| `system-weather` | Ward UI payload: calm/watch/act with trends +| `message-intent` | Command messaging between components +| `run-bundle` | Execution bundle with completion info +| `pack-manifest` | Scan pack definition with platform filters +| `ambient-payload` | Ambient mode indicator data +|=== + +The `contracts-rust/` crate provides Rust structs with `serde` serialization and `From` conversions from hardware-crash-team types. + +== Satellite Repos + +External tools that integrate with AmbientOps but live in their own repos: + +* **panic-attacker** — Software health scanner (feeds verisim) +* **verisim** / **verisim-data** — Multimodal database for scan results +* **hypatia** — Neurosymbolic CI/CD intelligence +* **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.) +* **echidna** — Neurosymbolic theorem proving (30 prover backends) +* **network-orchestrator** — Enterprise network management (planned) +* **traffic-conditioner** — Continuous network optimization (planned) + +== Safety and Trust Principles + +* No fearware claims ("304 errors fixed!") +* Evidence first: show measurements, not hype +* Scan is non-mutating by default +* Apply requires explicit approval +* DRY RUN by default for all destructive operations +* Undo and receipts are first-class +* Privacy controls are visible and simple (local-only by default) + +== License + +MPL-2.0 (Palimpsest License). + + +== Architecture + +See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md deleted file mode 100644 index eaf3d278..00000000 --- a/README.md +++ /dev/null @@ -1,150 +0,0 @@ - - -[![License: PMPL-1.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) [![Green Hosting](https://api.thegreenwebfoundation.org/greencheckimage/jewell.nexus)](https://www.thegreenwebfoundation.org/green-web-check/?url=jewell.nexus) - -AmbientOps is a hospital-model operations framework providing -**trustworthy system help** without fearware, nagware, or scammy -"optimizers". It is organised as a **hybrid monorepo**: core hospital -departments live here, external tools stay as satellites. - -# Quick Start - -```bash -# Build everything (requires just, cargo, mix, deno) -just build-all - -# Run all tests -just test-all - -# Build Rust components only -cargo build --workspace - -# Run hardware scan with contract-conformant output -cargo run -p hardware-crash-team -- scan --envelope - -# Generate remediation plan -cargo run -p hardware-crash-team -- plan 01:00.0 --procedure - -# Emergency room with envelope output -cd emergency-room && v run src/ trigger --envelope - -# Generate system weather -cd observatory && mix sysobs weather --output /tmp/ambientops/weather.json - -# Run end-to-end demo -./scripts/demo-flow.sh --build -``` - -# Component Status - -| Component | Language | Tests | Maturity | -|---------------------|-----------------|-------------|----------| -| contracts | JSON+Deno | 13 steps | 80% | -| contracts-rust | Rust | 7 | 80% | -| observatory | Elixir | 87 | 85% | -| emergency-room | V | 9 (3 files) | 75% | -| records/referrals | Elixir | 8 | 65% | -| hardware-crash-team | Rust | 27 | 75% | -| clinician | Rust | 16 | 55% | -| composer | Gleam (planned) | 0 | 10% | - -# The Hospital Model - -AmbientOps presents system tooling as four "departments": - -- **Ward** — System Weather + gentle ambient guidance (`observatory/`) - -- **Emergency Room** — Panic-safe intake with one-click stabilization - (`emergency-room/`) - -- **Operating Room** — Planned procedures: Scan → Plan → Apply → Undo → - Receipt (`clinician/`, `hardware-crash-team/`, `composer/`) - -- **Records** — Receipts, undo tokens, and referrals (`records/`) - -**Data flow:** Evidence Envelope → Procedure Plan → Receipt → System -Weather - -See `docs/HOSPITAL_MODEL.adoc` for the full model. - -# Directory Structure - - ambientops/ - ├── clinician/ (Rust, ~4400 LOC) — AI-assisted sysadmin [from personal-sysadmin] - ├── emergency-room/ (V, ~1800 LOC) — Panic-safe intake [from emergency-button] - ├── hardware-crash-team/ (Rust, ~700 LOC) — PCI zombie detection & remediation - ├── observatory/ (Elixir, ~600 LOC)— Metrics, weather, bundle ingestion - ├── contracts/ (JSON+Deno) — 8 JSON schemas + validators - ├── contracts-rust/ (Rust) — Serde types matching JSON schemas - ├── records/referrals/ (Elixir, ~400 LOC)— Multi-platform bug reporting MCP - ├── composer/ (Gleam, stubs) — Orchestration engine - ├── scripts/ — Demo and utility scripts - ├── docs/ — Documentation - ├── Cargo.toml — Rust workspace root - └── .machine_readable/ — .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/ECOSYSTEM.a2ml, .machine_readable/6a2/META.a2ml - -# Contract Schemas - -The `contracts/` directory contains 8 JSON schemas that define the -inter-component data format: - -| Schema | Purpose | -|---------------------|------------------------------------------------------| -| `evidence-envelope` | A&E intake / scan output with artifacts and findings | -| `procedure-plan` | Operating Theatre steps with risk and reversibility | -| `receipt` | Execution result with undo bundle and evidence | -| `system-weather` | Ward UI payload: calm/watch/act with trends | -| `message-intent` | Command messaging between components | -| `run-bundle` | Execution bundle with completion info | -| `pack-manifest` | Scan pack definition with platform filters | -| `ambient-payload` | Ambient mode indicator data | - -The `contracts-rust/` crate provides Rust structs with `serde` -serialization and `From` conversions from hardware-crash-team types. - -# Satellite Repos - -External tools that integrate with AmbientOps but live in their own -repos: - -- **panic-attacker** — Software health scanner (feeds verisim) - -- **verisim** / **verisim-data** — Multimodal database for scan results - -- **hypatia** — Neurosymbolic CI/CD intelligence - -- **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.) - -- **echidna** — Neurosymbolic theorem proving (30 prover backends) - -- **network-orchestrator** — Enterprise network management (planned) - -- **traffic-conditioner** — Continuous network optimization (planned) - -# Safety and Trust Principles - -- No fearware claims ("304 errors fixed!") - -- Evidence first: show measurements, not hype - -- Scan is non-mutating by default - -- Apply requires explicit approval - -- DRY RUN by default for all destructive operations - -- Undo and receipts are first-class - -- Privacy controls are visible and simple (local-only by default) - -# License - -MPL-2.0 (Palimpsest License). - -# Architecture - -See TOPOLOGY for a visual -architecture map and completion dashboard.