From b2218b8521a2a48363a46e6c88b7806d26229f47 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:40:18 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 172 ---------------------------------------------------- README.md | 147 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+), 172 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 02d0f13..0000000 --- a/README.adoc +++ /dev/null @@ -1,172 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell - -= Kea: Unified Infrastructure Orchestration Toolkit - -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://img.shields.io/badge/RSR-2026-brightgreen.svg[RSR 2026] -Jonathan D.A. Jewell -v1.0.0, March 2026 -:description: Monorepo for the Kea ecosystem — intelligent infrastructure orchestration, investigation, signalling, and WebAssembly interface tooling. -:toc: auto -:toclevels: 3 -:icons: font -:source-highlighter: rouge - -== Overview - -Kea is the unified monorepo for four core infrastructure tools, each named after a behavioural trait of the Kea parrot: strategic roosting, vocal coordination, investigative dexterity, and adaptive intelligence. - -The system provides a closed-loop audit-and-remediation pipeline: sensors probe infrastructure, signals are routed via zero-copy protocols, and the orchestrator executes playbooks to fix or alert. - -== Components - -[cols="1,2,3"] -|=== -|Directory |Component |Purpose - -|`bivouac/` -|**Kea-Bivouac** -- The Command Authority -|Orchestration and deployment controller. Manages the separation of administration from runtime, executes playbooks, enforces mTLS zero-trust communication. - -|`call/` -|**Kea-Call** -- The Contact-Signalling Protocol -|Cap'n Proto and MCP definitions for ecosystem communication. Zero-copy binary serialisation between sensors (Mandible) and logic (Wit) via the Request-Signal-Action loop. - -|`mandible/` -|**Kea-Mandible** -- The Investigative Mandible -|High-dexterity sensor suite. Contains four crates: Kea-Beak (filesystem/network auditor at 10k files/sec), Kea-Mandible CLI, WP-Praxis (WordPress core auditor), and Slop-Gate (bloat detection filter). - -|`wit/` -|**Kea-Wit** -- WebAssembly Interface Types -|WIT interface definitions and tooling for WebAssembly Component Model development, validation, and code generation. -|=== - -== Architecture - -.... - Kea-Call - Kea-Mandible -----(Cap'n Proto)-----> Kea-Wit - (Sensors) (Logic) - | | - | Kea-Bivouac | - +----------> (Orchestrator) <---------+ -.... - -See link:TOPOLOGY.md[TOPOLOGY.md] for a detailed architecture map, completion dashboard, and MVP roadmap. - -== Quick Start - -[source,bash] ----- -# Build all Rust components -just build - -# Run all tests -just test - -# Full check suite (format, lint, test) -just check - -# Deep audit a target path (via Mandible) -just mandible-pry /var/www/html - -# WordPress audit (via Mandible) -just mandible-wordpress /var/www/html - -# Execute a failover playbook (via Bivouac) -just bivouac-playbook integrity-violation - -# Security scan (pre-commit) -just panic ----- - -== Repository Structure - -[source] ----- -kea/ -├── bivouac/ # Kea-Bivouac (orchestration and deployment) -│ ├── src/ # Rust application source -│ ├── tests/ # Integration tests -│ ├── playbooks/ # TOML playbook definitions -│ └── fuzz/ # ClusterFuzzLite fuzz targets -├── call/ # Kea-Call (signalling protocol definitions) -├── mandible/ # Kea-Mandible (investigative sensors) -│ └── crates/ # Workspace: kea-beak, kea-mandible, wp-praxis, slop-gate -├── wit/ # Kea-Wit (WebAssembly interface types) -├── .github/workflows/ # 17 RSR-standard CI/CD workflows -├── .machine_readable/6a2/ # Machine-readable state (A2ML format) -├── .well-known/ # Security and AI discovery files -├── justfile # Top-level build recipes -├── TOPOLOGY.md # Architecture map and completion dashboard -├── LICENSE # MPL-2.0 (tooling compat; see NOTICE) -├── LICENSES/ # MPL-2.0.txt + MPL-2.0.txt -└── NOTICE # Licensing explanation ----- - -== Technology Stack - -Per the Hyperpolymath language policy: - -[cols="1,2"] -|=== -|Domain |Technology - -|Systems / Core -|Rust - -|Serialisation -|Cap'n Proto (zero-copy) - -|Interfaces -|WIT (WebAssembly Component Model) - -|Runtime (where JS needed) -|Deno - -|Configuration -|TOML, Nickel - -|ABI (planned) -|Idris2 - -|FFI (planned) -|Zig - -|API (planned) -|zig -|=== - -== Roadmap - -=== Phase 1: MVP (current) - -* Slop-Gate heuristic tuning (60% -> 90%) -* WP-Praxis edge case coverage (multisite, custom themes) -* WIT specification formalisation -* End-to-end integration test: Mandible -> Call -> Bivouac - -=== Phase 2: ABI/FFI/API - -* Idris2 ABI definitions for cross-component type safety -* Zig FFI layer for C-compatible sensor plugins -* zig API connectors for external integrations - -=== Phase 3: Distribution - -* Chainguard-based OCI container image -* BoJ-server integration (Kea sensors as MCP cartridge data sources) -* Crate publication to crates.io - -== License - -Licensed under link:LICENSES/MPL-2.0.txt[MPL-2.0] (Palimpsest License). - -The root `LICENSE` file contains MPL-2.0 for tooling compatibility. See link:NOTICE[NOTICE] for details. - -Copyright (C) 2024-2026 Jonathan D.A. Jewell - -== Author - -Jonathan D.A. Jewell diff --git a/README.md b/README.md new file mode 100644 index 0000000..8d79697 --- /dev/null +++ b/README.md @@ -0,0 +1,147 @@ + + +[![License: PMPL-1.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) ![RSR +2026](https://img.shields.io/badge/RSR-2026-brightgreen.svg) Jonathan +D.A. Jewell \<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> v1.0.0, +March 2026 :description: Monorepo for the Kea ecosystem — intelligent +infrastructure orchestration, investigation, signalling, and WebAssembly +interface tooling. :toc: auto :toclevels: 3 :icons: font +:source-highlighter: rouge + +# Overview + +Kea is the unified monorepo for four core infrastructure tools, each +named after a behavioural trait of the Kea parrot: strategic roosting, +vocal coordination, investigative dexterity, and adaptive intelligence. + +The system provides a closed-loop audit-and-remediation pipeline: +sensors probe infrastructure, signals are routed via zero-copy +protocols, and the orchestrator executes playbooks to fix or alert. + +# Components + +| Directory | Component | Purpose | +|----|----|----| +| `bivouac/` | **Kea-Bivouac** — The Command Authority | Orchestration and deployment controller. Manages the separation of administration from runtime, executes playbooks, enforces mTLS zero-trust communication. | +| `call/` | **Kea-Call** — The Contact-Signalling Protocol | Cap’n Proto and MCP definitions for ecosystem communication. Zero-copy binary serialisation between sensors (Mandible) and logic (Wit) via the Request-Signal-Action loop. | +| `mandible/` | **Kea-Mandible** — The Investigative Mandible | High-dexterity sensor suite. Contains four crates: Kea-Beak (filesystem/network auditor at 10k files/sec), Kea-Mandible CLI, WP-Praxis (WordPress core auditor), and Slop-Gate (bloat detection filter). | +| `wit/` | **Kea-Wit** — WebAssembly Interface Types | WIT interface definitions and tooling for WebAssembly Component Model development, validation, and code generation. | + +# Architecture + + Kea-Call + Kea-Mandible -----(Cap'n Proto)-----> Kea-Wit + (Sensors) (Logic) + | | + | Kea-Bivouac | + +----------> (Orchestrator) <---------+ + +See TOPOLOGY for a detailed +architecture map, completion dashboard, and MVP roadmap. + +# Quick Start + +```bash +# Build all Rust components +just build + +# Run all tests +just test + +# Full check suite (format, lint, test) +just check + +# Deep audit a target path (via Mandible) +just mandible-pry /var/www/html + +# WordPress audit (via Mandible) +just mandible-wordpress /var/www/html + +# Execute a failover playbook (via Bivouac) +just bivouac-playbook integrity-violation + +# Security scan (pre-commit) +just panic +``` + +# Repository Structure + + kea/ + ├── bivouac/ # Kea-Bivouac (orchestration and deployment) + │ ├── src/ # Rust application source + │ ├── tests/ # Integration tests + │ ├── playbooks/ # TOML playbook definitions + │ └── fuzz/ # ClusterFuzzLite fuzz targets + ├── call/ # Kea-Call (signalling protocol definitions) + ├── mandible/ # Kea-Mandible (investigative sensors) + │ └── crates/ # Workspace: kea-beak, kea-mandible, wp-praxis, slop-gate + ├── wit/ # Kea-Wit (WebAssembly interface types) + ├── .github/workflows/ # 17 RSR-standard CI/CD workflows + ├── .machine_readable/6a2/ # Machine-readable state (A2ML format) + ├── .well-known/ # Security and AI discovery files + ├── justfile # Top-level build recipes + ├── TOPOLOGY.md # Architecture map and completion dashboard + ├── LICENSE # MPL-2.0 (tooling compat; see NOTICE) + ├── LICENSES/ # MPL-2.0.txt + MPL-2.0.txt + └── NOTICE # Licensing explanation + +# Technology Stack + +Per the Hyperpolymath language policy: + +| Domain | Technology | +|---------------------------|-----------------------------------| +| Systems / Core | Rust | +| Serialisation | Cap’n Proto (zero-copy) | +| Interfaces | WIT (WebAssembly Component Model) | +| Runtime (where JS needed) | Deno | +| Configuration | TOML, Nickel | +| ABI (planned) | Idris2 | +| FFI (planned) | Zig | +| API (planned) | zig | + +# Roadmap + +## Phase 1: MVP (current) + +- Slop-Gate heuristic tuning (60% → 90%) + +- WP-Praxis edge case coverage (multisite, custom themes) + +- WIT specification formalisation + +- End-to-end integration test: Mandible → Call → Bivouac + +## Phase 2: ABI/FFI/API + +- Idris2 ABI definitions for cross-component type safety + +- Zig FFI layer for C-compatible sensor plugins + +- zig API connectors for external integrations + +## Phase 3: Distribution + +- Chainguard-based OCI container image + +- BoJ-server integration (Kea sensors as MCP cartridge data sources) + +- Crate publication to crates.io + +# License + +Licensed under MPL-2 +(Palimpsest License). + +The root `LICENSE` file contains MPL-2.0 for tooling compatibility. See +[NOTICE](NOTICE) for details. + +Copyright © 2024-2026 Jonathan D.A. Jewell +\<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\> + +# Author + +Jonathan D.A. Jewell \<[j.d.a.jewell@open.ac](j.d.a.jewell@open.ac).uk\>