From 46478434a4bb26941a409a355ad557990e4f9046 Mon Sep 17 00:00:00 2001
From: JohnE <git@malloc.io>
Date: Mon, 2 Mar 2026 23:40:27 -0800
Subject: [PATCH] MOD: updating readme

---
 README.md  | 92 ------------------------------------------------------
 README.rst | 29 +++++++++++++++++
 2 files changed, 29 insertions(+), 92 deletions(-)
 delete mode 100644 README.md

diff --git a/README.md b/README.md
deleted file mode 100644
index 1f27790..0000000
--- a/README.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# ccc_cryptography
-
-A new Flutter FFI plugin project.
-
-## Getting Started
-
-This project is a starting point for a Flutter
-[FFI plugin](https://flutter.dev/to/ffi-package),
-a specialized package that includes native code directly invoked with Dart FFI.
-
-## Project structure
-
-This template uses the following structure:
-
-* `src`: Contains the native source code, and a CmakeFile.txt file for building
-  that source code into a dynamic library.
-
-* `lib`: Contains the Dart code that defines the API of the plugin, and which
-  calls into the native code using `dart:ffi`.
-
-* platform folders (`android`, `ios`, `windows`, etc.): Contains the build files
-  for building and bundling the native code library with the platform application.
-
-## Building and bundling native code
-
-The `pubspec.yaml` specifies FFI plugins as follows:
-
-```yaml
-  plugin:
-    platforms:
-      some_platform:
-        ffiPlugin: true
-```
-
-This configuration invokes the native build for the various target platforms
-and bundles the binaries in Flutter applications using these FFI plugins.
-
-This can be combined with dartPluginClass, such as when FFI is used for the
-implementation of one platform in a federated plugin:
-
-```yaml
-  plugin:
-    implements: some_other_plugin
-    platforms:
-      some_platform:
-        dartPluginClass: SomeClass
-        ffiPlugin: true
-```
-
-A plugin can have both FFI and method channels:
-
-```yaml
-  plugin:
-    platforms:
-      some_platform:
-        pluginClass: SomeName
-        ffiPlugin: true
-```
-
-The native build systems that are invoked by FFI (and method channel) plugins are:
-
-* For Android: Gradle, which invokes the Android NDK for native builds.
-  * See the documentation in android/build.gradle.
-* For iOS and MacOS: Xcode, via CocoaPods.
-  * See the documentation in ios/ccc_cryptography.podspec.
-  * See the documentation in macos/ccc_cryptography.podspec.
-* For Linux and Windows: CMake.
-  * See the documentation in linux/CMakeLists.txt.
-  * See the documentation in windows/CMakeLists.txt.
-
-## Binding to native code
-
-To use the native code, bindings in Dart are needed.
-To avoid writing these by hand, they are generated from the header file
-(`src/ccc_cryptography.h`) by `package:ffigen`.
-Regenerate the bindings by running `dart run ffigen --config ffigen.yaml`.
-
-## Invoking native code
-
-Very short-running native functions can be directly invoked from any isolate.
-For example, see `sum` in `lib/ccc_cryptography.dart`.
-
-Longer-running functions should be invoked on a helper isolate to avoid
-dropping frames in Flutter applications.
-For example, see `sumAsync` in `lib/ccc_cryptography.dart`.
-
-## Flutter help
-
-For help getting started with Flutter, view our
-[online documentation](https://docs.flutter.dev), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
-
diff --git a/README.rst b/README.rst
index bf132c5..05b78ba 100644
--- a/README.rst
+++ b/README.rst
@@ -2,4 +2,33 @@
 Copius Cipher Chain Cryptography Library
 ========================================
 
+Overview
+========
+
+This document describes the architecture for the **CCC Rust Crypto Provider**,
+the first of three milestones in delivering hardware-grade cryptography to the
+LetUsMsg application.
+
+===================================  ==========================  ===========================
+Repository                           What ships                  Depends on
+===================================  ==========================  ===========================
+``ccc_rust``                         Pure Rust crypto library    wolfSSL (vendored)
+``ccc_dart_plugin``                  Flutter plugin + Dart API   ``ccc_rust`` (git/semver)
+``letusmsg`` (existing app)          App integration             ``ccc_dart_plugin`` package
+===================================  ==========================  ===========================
+
+
+Guiding Principles
+~~~~~~~~~~~~~~~~~~
+
+1. Every provider reports its own capabilities at runtime — no compile-time
+   hard-coding of ``available: true/false``.
+2. Algorithm IDs in Rust map 1-to-1 to the integer constants in
+   ``cipher_constants.dart`` — zero Dart changes needed when wiring up.
+3. Key material is zeroed on drop (``zeroize`` crate) everywhere.
+4. A conformance test suite validates NIST/RFC vectors for every algorithm
+   before any provider is marked ``available``.
+5. The library has no runtime dependency on Flutter; it is consumable by any
+   FFI host (Flutter plugin, Python tests, CLI tools).
+