From dc7c4ce2a0ddf14b8a7506d9fa2e585be2b4d49e Mon Sep 17 00:00:00 2001
From: Sami Ahmed <sami@sami-ahmed.net>
Date: Thu, 16 Jul 2026 02:57:37 -0700
Subject: [PATCH] Update README to reflect the nyc3 source import + test
 scaffolding.

---
 README.md | 88 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 68 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 829f176fa..e7b799006 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,76 @@
 # CAC3 (Californiacoin3) — integration/staging tree
 
-## What this is
-A fork of Bitcoin Core 0.18 with a CPU-mineable proof-of-work (Argon2s),
-a difficulty-adjustment algorithm tuned for fast block spacing (LWMA-3),
-and 10-second block times — explicitly designed to keep mining fair to
-anyone with general-purpose hardware.
+A fork of **Bitcoin Core 0.18** carrying a CPU-mineable proof-of-work
+(Argon2s), LWMA-3 difficulty targeting, and 10-second block times —
+explicitly designed to keep mining fair to anyone with general-purpose
+hardware.
 
-The full body of work is being brought over from
-[SamiAhmed7777/nyc3](https://github.com/SamiAhmed7777/nyc3), the previous
-identity this codebase ran under, with the consensus algorithm and
-parameters held constant — only the chain identity (genesis, magic bytes,
-ports, address prefixes, ticker) is changing.
+The chain source is the **barrystyle/nyc3** codebase (NewYorkCoin3),
+imported on top of the CAC3 art tree. The chain identity (genesis,
+magic bytes, ports, address prefixes, ticker) is still nyc3's and will
+be renamed to CAC3 in a follow-up commit.
+
+## What this repo contains
+
+```
+.
+├── art/                  # CAC3 icons, splash, and visual assets
+│   ├── icons/            # 20 PNG/ICO files, multi-size (16→1024)
+│   └── splash/           # splash-v2.{png,jpg} + README
+├── src/                  # C++ source — Bitcoin Core 0.18 fork (nyc3 base)
+│   ├── chainparams.cpp   # network params (still nyc3; will become CAC3)
+│   ├── pow.cpp           # Argon2s PoW check
+│   ├── validation.cpp    # block + tx validation
+│   └── ...               # full Bitcoin Core tree
+├── test/                 # python functional tests (115 files)
+├── src/test/             # boost unit tests (70 files)
+├── doc/                  # build docs, developer notes
+├── contrib/              # gitian, debian packaging, etc.
+├── configure.ac          # autotools
+├── scripts/test.sh       # one-shot: install deps + run all tests
+├── CAC3-LAUNCH.md        # rename plan, pending
+└── README.md             # this file
+```
+
+## Building & testing
+
+Tomorrow's first step:
+
+```bash
+bash scripts/test.sh          # full suite (unit + functional)
+bash scripts/test.sh --quick  # unit only
+bash scripts/test.sh --clean  # nuke build/ first
+```
+
+`scripts/test.sh` auto-installs Debian/Ubuntu deps, runs autogen,
+configures with `--disable-wallet --without-gui`, builds the test
+binary, and runs both the boost unit suite and the python functional
+suite. Logs land in `.test-logs/test-<timestamp>.log`.
 
 ## Status
-Initial repo creation. No source has been pushed yet. The rename and
-fresh genesis block are pending a deliberate launch step.
+
+| Step | Status |
+|---|---|
+| Icon set (art/icons/) | ✅ shipped (20 sizes, app-store + favicon) |
+| Splash v2 (art/splash/) | ✅ shipped |
+| Source import from nyc3 | ✅ shipped (1,702 files, 19,856 commits of history reachable) |
+| Build & test scaffolding (`scripts/test.sh`) | ✅ shipped |
+| Chain-identity rename (genesis / ports / prefix / ticker) | 🟡 pending — see `CAC3-LAUNCH.md` |
+| Build verification (`bash scripts/test.sh`) | 🟡 pending — runs tomorrow |
+| Block explorer (`cac3-explorer` repo) | 🟡 in progress |
 
 ## License
-MIT — see COPYING once the upstream Bitcoin Core license stub lands.
 
-## Acknowledgement
-The Argon2s implementation, the LWMA-3 difficulty algorithm, and the
-base Bitcoin Core 0.18 fork that this project stands on come from the
-open-source ecosystem around [barrystyle](https://github.com/barrystyle),
-[barrystyle/argon2s](https://github.com/barrystyle/argon2s), and
-[barrystyle/nyc3](https://github.com/barrystyle/nyc3). This fork honours
-their work.
+MIT — see `COPYING`. The Argon2s implementation, the LWMA-3 difficulty
+algorithm, and the base Bitcoin Core 0.18 fork that this project
+stands on come from the open-source ecosystem around
+[barrystyle](https://github.com/barrystyle) and
+[barrystyle/nyc3](https://github.com/barrystyle/nyc3). This fork
+honours their work.
+
+## Mirror
+
+This repo is also hosted at https://github.com/SamiAhmed7777/cac3
+(the original push was a 4-commit art-only tree; the
+`nyc3-source` import + test scaffolding has since been added here on
+git.sami).