Skip to content

Commit 3583dd6

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
docs(readme): convert README.adoc -> Markdown (renders on Glama/profile/community-health) (#205)
README was AsciiDoc → renders as raw markup in Markdown consumers (Glama MCP directory, GitHub community-health, GitHub profile). pandoc asciidoc→GFM (badges → clickable), SPDX header kept, duplicate `.adoc` removed. Part of the estate README-format fix. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 8b34d38 commit 3583dd6

2 files changed

Lines changed: 109 additions & 243 deletions

File tree

‎README.adoc‎

Lines changed: 0 additions & 141 deletions
This file was deleted.

‎README.md‎

Lines changed: 109 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,18 @@
1-
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath)
1+
<!--
2+
SPDX-License-Identifier: CC-BY-SA-4.0
3+
SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
-->
25

3-
// SPDX-License-Identifier: CC-BY-SA-4.0
4-
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
5-
= AmbientOps
6+
[![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)
67

7-
image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"]
8-
image:https://api.thegreenwebfoundation.org/greencheckimage/jewell.nexus[Green Hosting,link="https://www.thegreenwebfoundation.org/green-web-check/?url=jewell.nexus"]
8+
AmbientOps is a hospital-model operations framework providing
9+
**trustworthy system help** without fearware, nagware, or scammy
10+
"optimizers". It is organised as a **hybrid monorepo**: core hospital
11+
departments live here, external tools stay as satellites.
912

10-
:toc:
11-
:toclevels: 3
12-
:icons: font
13-
:source-highlighter: rouge
13+
# Quick Start
1414

15-
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.
16-
17-
== Quick Start
18-
19-
[source,bash]
20-
----
15+
```bash
2116
# Build everything (requires just, cargo, mix, deno)
2217
just build-all
2318

@@ -41,103 +36,115 @@ cd observatory && mix sysobs weather --output /tmp/ambientops/weather.json
4136

4237
# Run end-to-end demo
4338
./scripts/demo-flow.sh --build
44-
----
39+
```
4540

46-
== Component Status
41+
# Component Status
4742

48-
[cols="1,1,1,1"]
49-
|===
50-
| Component | Language | Tests | Maturity
43+
| Component | Language | Tests | Maturity |
44+
|---------------------|-----------------|-------------|----------|
45+
| contracts | JSON+Deno | 13 steps | 80% |
46+
| contracts-rust | Rust | 7 | 80% |
47+
| observatory | Elixir | 87 | 85% |
48+
| emergency-room | V | 9 (3 files) | 75% |
49+
| records/referrals | Elixir | 8 | 65% |
50+
| hardware-crash-team | Rust | 27 | 75% |
51+
| clinician | Rust | 16 | 55% |
52+
| composer | Gleam (planned) | 0 | 10% |
5153

52-
| contracts | JSON+Deno | 13 steps | 80%
53-
| contracts-rust | Rust | 7 | 80%
54-
| observatory | Elixir | 87 | 85%
55-
| emergency-room | V | 9 (3 files) | 75%
56-
| records/referrals | Elixir | 8 | 65%
57-
| hardware-crash-team | Rust | 27 | 75%
58-
| clinician | Rust | 16 | 55%
59-
| composer | Gleam (planned) | 0 | 10%
60-
|===
61-
62-
== The Hospital Model
54+
# The Hospital Model
6355

6456
AmbientOps presents system tooling as four "departments":
6557

66-
* **Ward** — System Weather + gentle ambient guidance (`observatory/`)
67-
* **Emergency Room** — Panic-safe intake with one-click stabilization (`emergency-room/`)
68-
* **Operating Room** — Planned procedures: Scan → Plan → Apply → Undo → Receipt (`clinician/`, `hardware-crash-team/`, `composer/`)
69-
* **Records** — Receipts, undo tokens, and referrals (`records/`)
58+
- **Ward** — System Weather + gentle ambient guidance (`observatory/`)
59+
60+
- **Emergency Room** — Panic-safe intake with one-click stabilization
61+
(`emergency-room/`)
7062

71-
**Data flow:** Evidence Envelope → Procedure Plan → Receipt → System Weather
63+
- **Operating Room** — Planned procedures: Scan → Plan → Apply → Undo →
64+
Receipt (`clinician/`, `hardware-crash-team/`, `composer/`)
65+
66+
- **Records** — Receipts, undo tokens, and referrals (`records/`)
67+
68+
**Data flow:** Evidence Envelope → Procedure Plan → Receipt → System
69+
Weather
7270

7371
See `docs/HOSPITAL_MODEL.adoc` for the full model.
7472

75-
== Directory Structure
76-
77-
[source]
78-
----
79-
ambientops/
80-
├── clinician/ (Rust, ~4400 LOC) — AI-assisted sysadmin [from personal-sysadmin]
81-
├── emergency-room/ (V, ~1800 LOC) — Panic-safe intake [from emergency-button]
82-
├── hardware-crash-team/ (Rust, ~700 LOC) — PCI zombie detection & remediation
83-
├── observatory/ (Elixir, ~600 LOC)— Metrics, weather, bundle ingestion
84-
├── contracts/ (JSON+Deno) — 8 JSON schemas + validators
85-
├── contracts-rust/ (Rust) — Serde types matching JSON schemas
86-
├── records/referrals/ (Elixir, ~400 LOC)— Multi-platform bug reporting MCP
87-
├── composer/ (Gleam, stubs) — Orchestration engine
88-
├── scripts/ — Demo and utility scripts
89-
├── docs/ — Documentation
90-
├── Cargo.toml — Rust workspace root
91-
└── .machine_readable/ — .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/ECOSYSTEM.a2ml, .machine_readable/6a2/META.a2ml
92-
----
93-
94-
== Contract Schemas
95-
96-
The `contracts/` directory contains 8 JSON schemas that define the inter-component data format:
97-
98-
[cols="1,2"]
99-
|===
100-
| Schema | Purpose
101-
102-
| `evidence-envelope` | A&E intake / scan output with artifacts and findings
103-
| `procedure-plan` | Operating Theatre steps with risk and reversibility
104-
| `receipt` | Execution result with undo bundle and evidence
105-
| `system-weather` | Ward UI payload: calm/watch/act with trends
106-
| `message-intent` | Command messaging between components
107-
| `run-bundle` | Execution bundle with completion info
108-
| `pack-manifest` | Scan pack definition with platform filters
109-
| `ambient-payload` | Ambient mode indicator data
110-
|===
111-
112-
The `contracts-rust/` crate provides Rust structs with `serde` serialization and `From` conversions from hardware-crash-team types.
113-
114-
== Satellite Repos
115-
116-
External tools that integrate with AmbientOps but live in their own repos:
117-
118-
* **panic-attacker** — Software health scanner (feeds verisim)
119-
* **verisim** / **verisim-data** — Multimodal database for scan results
120-
* **hypatia** — Neurosymbolic CI/CD intelligence
121-
* **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.)
122-
* **echidna** — Neurosymbolic theorem proving (30 prover backends)
123-
* **network-orchestrator** — Enterprise network management (planned)
124-
* **traffic-conditioner** — Continuous network optimization (planned)
125-
126-
== Safety and Trust Principles
127-
128-
* No fearware claims ("304 errors fixed!")
129-
* Evidence first: show measurements, not hype
130-
* Scan is non-mutating by default
131-
* Apply requires explicit approval
132-
* DRY RUN by default for all destructive operations
133-
* Undo and receipts are first-class
134-
* Privacy controls are visible and simple (local-only by default)
135-
136-
== License
73+
# Directory Structure
13774

138-
MPL-2.0 (Palimpsest License).
75+
ambientops/
76+
├── clinician/ (Rust, ~4400 LOC) — AI-assisted sysadmin [from personal-sysadmin]
77+
├── emergency-room/ (V, ~1800 LOC) — Panic-safe intake [from emergency-button]
78+
├── hardware-crash-team/ (Rust, ~700 LOC) — PCI zombie detection & remediation
79+
├── observatory/ (Elixir, ~600 LOC)— Metrics, weather, bundle ingestion
80+
├── contracts/ (JSON+Deno) — 8 JSON schemas + validators
81+
├── contracts-rust/ (Rust) — Serde types matching JSON schemas
82+
├── records/referrals/ (Elixir, ~400 LOC)— Multi-platform bug reporting MCP
83+
├── composer/ (Gleam, stubs) — Orchestration engine
84+
├── scripts/ — Demo and utility scripts
85+
├── docs/ — Documentation
86+
├── Cargo.toml — Rust workspace root
87+
└── .machine_readable/ — .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/ECOSYSTEM.a2ml, .machine_readable/6a2/META.a2ml
88+
89+
# Contract Schemas
90+
91+
The `contracts/` directory contains 8 JSON schemas that define the
92+
inter-component data format:
93+
94+
| Schema | Purpose |
95+
|---------------------|------------------------------------------------------|
96+
| `evidence-envelope` | A&E intake / scan output with artifacts and findings |
97+
| `procedure-plan` | Operating Theatre steps with risk and reversibility |
98+
| `receipt` | Execution result with undo bundle and evidence |
99+
| `system-weather` | Ward UI payload: calm/watch/act with trends |
100+
| `message-intent` | Command messaging between components |
101+
| `run-bundle` | Execution bundle with completion info |
102+
| `pack-manifest` | Scan pack definition with platform filters |
103+
| `ambient-payload` | Ambient mode indicator data |
104+
105+
The `contracts-rust/` crate provides Rust structs with `serde`
106+
serialization and `From` conversions from hardware-crash-team types.
107+
108+
# Satellite Repos
109+
110+
External tools that integrate with AmbientOps but live in their own
111+
repos:
112+
113+
- **panic-attacker** — Software health scanner (feeds verisim)
114+
115+
- **verisim** / **verisim-data** — Multimodal database for scan results
139116

117+
- **hypatia** — Neurosymbolic CI/CD intelligence
118+
119+
- **gitbot-fleet** — Bot orchestration (rhodibot, echidnabot, etc.)
120+
121+
- **echidna** — Neurosymbolic theorem proving (30 prover backends)
122+
123+
- **network-orchestrator** — Enterprise network management (planned)
124+
125+
- **traffic-conditioner** — Continuous network optimization (planned)
126+
127+
# Safety and Trust Principles
128+
129+
- No fearware claims ("304 errors fixed!")
130+
131+
- Evidence first: show measurements, not hype
132+
133+
- Scan is non-mutating by default
134+
135+
- Apply requires explicit approval
136+
137+
- DRY RUN by default for all destructive operations
138+
139+
- Undo and receipts are first-class
140+
141+
- Privacy controls are visible and simple (local-only by default)
142+
143+
# License
144+
145+
MPL-2.0 (Palimpsest License).
140146

141-
== Architecture
147+
# Architecture
142148

143-
See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.
149+
See <a href="TOPOLOGY.md" class="md">TOPOLOGY</a> for a visual
150+
architecture map and completion dashboard.

0 commit comments

Comments
 (0)