From 7576b27493c848819ec733e41af93cfcc00a44ef Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:17:31 +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 | 101 -------------------------------------- README.md | 138 ++++++++++++++++++++++++++++++---------------------- 2 files changed, 79 insertions(+), 160 deletions(-) delete mode 100644 README.adoc diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 423778d..0000000 --- a/README.adoc +++ /dev/null @@ -1,101 +0,0 @@ -= DotMatrix-FilePrinter (Enhanced Suite) -:author: Jonathan D.A. Jewell -:revnumber: 2026.01.14 -:doctype: book -:toc: macro -:sectnums: -:icons: font - -[abstract] -A Neurosymbolic approach to filesystem manipulation. This tool treats the filesystem as a 24-pin dot-matrix substrate for deterministic, byte-level injection, eliminating encoding drift and NBSP contamination. - -toc::[] - -== 1. Philosophy: The Physical Byte -This suite treats the filesystem not as a collection of high-level abstractions, but as a physical tape where every bit is a mechanical strike. By utilizing a **Forth Kernel** as the primary "Print Head," we ensure that the **physical byte is the ultimate source of truth.** - -* **Neural Layer:** `rescript-tea` + `cadre-tea-router` (Visualising intent and routing). -* **Symbolic Layer:** `Nickel` (Defining the declarative contract and metadata). -* **Physical Layer:** `Forth` (Stack-based deterministic execution). -* **Bridge Layer:** `gossamer-rs` + `RuntimeBridge.res` (Type-safe OS-level integration). - -== 2. Technical Stack & Requirements - -The suite is built for cross-platform stability (Linux, Minix, macOS, iOS, Android, and PC). - -* **Orchestration:** `just` (strictly no `make`). -* **Configuration:** `Nickel` (exporting to Forth/JSON). -* **Frontend:** `ReScript` + `rescript-tea`. -* **Backend:** `Gossamer (Rust)` + `Gforth`. -* **Verification:** `hexdump` + `grep` (Binary verification). - -== 3. Must-Just-Nickel Workflow - -All automation is managed via `just`. The following recipes are defined in the `justfile`. - -[source,bash] ----- -# Default: Full Neurosymbolic Strike -just all - -# Physical Strike: Injects bytes via Forth Kernel -# Usage: just strike "104,101,108,108,111" -just strike - -# Verification: Prove the substrate is ASCII-clean (no 0xA0) -just verify - -# Deploy: Package as a Podman container -just deploy ----- - -== 4. Component Architecture - -=== 4.1 The Forth Kernel (`kernel/striker.fth`) -The "Print Head" logic. It processes the stack into a vertical 24-pin alignment. - -=== 4.2 The TEA UI (`src/App.res`) -Uses `rescript-tea` to provide a real-time monitor of the Forth stack and the "Inking" path on the substrate grid. - -=== 4.3 Nickel Contracts (`config/meta.ncl`) -Symbolic constraints that prevent "Neural Drift." It ensures no byte > 127 is ever passed to the physical striker. - -== 5. Multi-Shell Registry - -While the primary logic resides in the `justfile` and `bash` wrappers, the suite provides native shims for 18+ shells in `bin/references/`. - -[cols="1,2,2"] -|=== -| Shell Type | Reference Script | Context - -| **Bash** | `bin/strike.sh` | Primary/README Default -| **Powershell-Core** | `bin/references/strike.ps1` | PC/Windows Substrates -| **Minix Shell** | `bin/references/strike.sh` | Minimalist -|=== - -== 6. Deployment & Edge Tech - -Following a **nerdctl-first** commitment, the suite is containerized for deterministic behavior across different host substrates. For **ASICs** or **Edge tech**, the Forth kernel is compiled into a standalone binary using `gforth` cross-compilation. - -[IMPORTANT] -If you require a build automation change, update the `justfile` and the `Cookbook.adoc`. - -== 7. Verification Proofs - -To verify a strike, do not use `cat` or `nano`. Use the physical truth: - -[source,bash] ----- -hexdump -C dist/substrate.bin ----- - ---- - -== 8. Appendix: Cookbook -See `Cookbook.adoc` for a full list of physical strike patterns and Forth-stack operation mappings. ----- - - -== Architecture - -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md index 9b5db3f..109d46c 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,55 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) + -= DotMatrix-FilePrinter (Enhanced Suite) -:author: Jonathan D.A. Jewell -:revnumber: 2026.01.14 -:doctype: book -:toc: macro -:sectnums: -:icons: font +A Neurosymbolic approach to filesystem manipulation. This tool treats +the filesystem as a 24-pin dot-matrix substrate for deterministic, +byte-level injection, eliminating encoding drift and NBSP contamination. -[abstract] -A Neurosymbolic approach to filesystem manipulation. This tool treats the filesystem as a 24-pin dot-matrix substrate for deterministic, byte-level injection, eliminating encoding drift and NBSP contamination. +
-toc::[] +
-== 1. Philosophy: The Physical Byte -This suite treats the filesystem not as a collection of high-level abstractions, but as a physical tape where every bit is a mechanical strike. By utilizing a **Forth Kernel** as the primary "Print Head," we ensure that the **physical byte is the ultimate source of truth.** + 1. Philosophy: The Physical Byte -* **Neural Layer:** `rescript-tea` + `cadre-tea-router` (Visualising intent and routing). -* **Symbolic Layer:** `Nickel` (Defining the declarative contract and metadata). -* **Physical Layer:** `Forth` (Stack-based deterministic execution). -* **Bridge Layer:** `gossamer-rs` + `RuntimeBridge.res` (Type-safe OS-level integration). +This suite treats the filesystem not as a collection of high-level +abstractions, but as a physical tape where every bit is a mechanical +strike. By utilizing a **Forth Kernel** as the primary "Print Head," we +ensure that the **physical byte is the ultimate source of truth.** -== 2. Technical Stack & Requirements +- **Neural Layer:** `rescript-tea` + `cadre-tea-router` (Visualising + intent and routing). -The suite is built for cross-platform stability (Linux, Minix, macOS, iOS, Android, and PC). +- **Symbolic Layer:** `Nickel` (Defining the declarative contract and + metadata). -* **Orchestration:** `just` (strictly no `make`). -* **Configuration:** `Nickel` (exporting to Forth/JSON). -* **Frontend:** `ReScript` + `rescript-tea`. -* **Backend:** `Gossamer (Rust)` + `Gforth`. -* **Verification:** `hexdump` + `grep` (Binary verification). +- **Physical Layer:** `Forth` (Stack-based deterministic execution). -== 3. Must-Just-Nickel Workflow +- **Bridge Layer:** `gossamer-rs` + `RuntimeBridge.res` (Type-safe + OS-level integration). -All automation is managed via `just`. The following recipes are defined in the `justfile`. + 2. Technical Stack & Requirements -[source,bash] ----- +The suite is built for cross-platform stability (Linux, Minix, macOS, +iOS, Android, and PC). + +- **Orchestration:** `just` (strictly no `make`). + +- **Configuration:** `Nickel` (exporting to Forth/JSON). + +- **Frontend:** `ReScript` + `rescript-tea`. + +- **Backend:** `Gossamer` `(Rust)` + `Gforth`. + +- **Verification:** `hexdump` + `grep` (Binary verification). + + 3. Must-Just-Nickel Workflow + +All automation is managed via `just`. The following recipes are defined +in the `justfile`. + +```bash # Default: Full Neurosymbolic Strike just all @@ -49,55 +62,62 @@ just verify # Deploy: Package as a Podman container just deploy ----- +``` + + 4. Component Architecture + +## 4.1 The Forth Kernel (`kernel/striker.fth`) -== 4. Component Architecture +The "Print Head" logic. It processes the stack into a vertical 24-pin +alignment. -=== 4.1 The Forth Kernel (`kernel/striker.fth`) -The "Print Head" logic. It processes the stack into a vertical 24-pin alignment. +## 4.2 The TEA UI (`src/App.res`) -=== 4.2 The TEA UI (`src/App.res`) -Uses `rescript-tea` to provide a real-time monitor of the Forth stack and the "Inking" path on the substrate grid. +Uses `rescript-tea` to provide a real-time monitor of the Forth stack +and the "Inking" path on the substrate grid. -=== 4.3 Nickel Contracts (`config/meta.ncl`) -Symbolic constraints that prevent "Neural Drift." It ensures no byte > 127 is ever passed to the physical striker. +## 4.3 Nickel Contracts (`config/meta.ncl`) -== 5. Multi-Shell Registry +Symbolic constraints that prevent "Neural Drift." It ensures no byte \> +127 is ever passed to the physical striker. -While the primary logic resides in the `justfile` and `bash` wrappers, the suite provides native shims for 18+ shells in `bin/references/`. + 5. Multi-Shell Registry -[cols="1,2,2"] -|=== -| Shell Type | Reference Script | Context +While the primary logic resides in the `justfile` and `bash` wrappers, +the suite provides native shims for 18+ shells in `bin/references/`. -| **Bash** | `bin/strike.sh` | Primary/README Default -| **Powershell-Core** | `bin/references/strike.ps1` | PC/Windows Substrates -| **Minix Shell** | `bin/references/strike.sh` | Minimalist -|=== +| Shell Type | Reference Script | Context | +|---------------------|-----------------------------|------------------------| +| **Bash** | `bin/strike.sh` | Primary/README Default | +| **Powershell-Core** | `bin/references/strike.ps1` | PC/Windows Substrates | +| **Minix Shell** | `bin/references/strike.sh` | Minimalist | -== 6. Deployment & Edge Tech + 6. Deployment & Edge Tech -Following a **nerdctl-first** commitment, the suite is containerized for deterministic behavior across different host substrates. For **ASICs** or **Edge tech**, the Forth kernel is compiled into a standalone binary using `gforth` cross-compilation. +Following a **nerdctl-first** commitment, the suite is containerized for +deterministic behavior across different host substrates. For **ASICs** +or **Edge tech**, the Forth kernel is compiled into a standalone binary +using `gforth` cross-compilation. -[IMPORTANT] -If you require a build automation change, update the `justfile` and the `Cookbook.adoc`. +If you require a build automation change, update the `justfile` and the +`Cookbook.adoc`. -== 7. Verification Proofs + 7. Verification Proofs To verify a strike, do not use `cat` or `nano`. Use the physical truth: -[source,bash] ----- +```bash hexdump -C dist/substrate.bin ----- +``` ---- +------------------------------------------------------------------------ -== 8. Appendix: Cookbook -See `Cookbook.adoc` for a full list of physical strike patterns and Forth-stack operation mappings. ----- + 8. Appendix: Cookbook +See `Cookbook.adoc` for a full list of physical strike patterns and +Forth-stack operation mappings. ---- -== Architecture + Architecture -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. +See TOPOLOGY for a visual +architecture map and completion dashboard.