014 documentation developer guide

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
 # blockchain Development Guidelines
 
-Auto-generated from all feature plans. Last updated: 2026-04-11
+Auto-generated from all feature plans. Last updated: 2026-04-12
 
 ## Active Technologies
 - C++20 (`-std=c++20`) + Boost (Asio, Serialization), OpenSSL (SHA-256 via EVP), nlohmann/json (vendored `src/json.hpp`) (002-consensus-mechanism)
@@ -16,6 +16,8 @@ Auto-generated from all feature plans. Last updated: 2026-04-11
 - Boost.Serialization binary chunk files in temporary directories (cleaned per test) (012-integration-test-suite)
 - YAML (GitHub Actions workflow), C++20 (project under test) + GitHub Actions, MSYS2 (Windows), apt (Linux), Homebrew (macOS) (013-ci-cd-pipeline)
 - N/A (CI configuration only, no persistent storage) (013-ci-cd-pipeline)
+- GitHub-Flavored Markdown (documentation-only feature; no C++ changes) + N/A (Markdown files only; Mermaid diagrams rendered natively by GitHub) (014-documentation-developer-guide)
+- N/A (no persistence changes) (014-documentation-developer-guide)
 
 - C++20 (`-std=c++20`) + Boost (Asio, Serialization), OpenSSL, nlohmann/json (vendored `src/json.hpp`), Catch2 (test only) (001-code-constitution-audit)
 
@@ -43,9 +45,9 @@ C++20 (`-std=c++20`): Follow standard conventions
 - Do not include task numbers (e.g. T001, T010) in code comments. Comments should describe *what* or *why*, not reference planning artifacts.
 
 ## Recent Changes
+- 014-documentation-developer-guide: Added GitHub-Flavored Markdown (documentation-only feature; no C++ changes) + N/A (Markdown files only; Mermaid diagrams rendered natively by GitHub)
 - 013-ci-cd-pipeline: Added YAML (GitHub Actions workflow), C++20 (project under test) + GitHub Actions, MSYS2 (Windows), apt (Linux), Homebrew (macOS)
 - 012-integration-test-suite: Added C++20 (`-std=c++20`) + Boost (Asio, Serialization), OpenSSL (EVP SHA-256, X.509 cert generation), nlohmann/json (vendored `src/json.hpp`), Catch2 (test framework)
-- 011-graceful-lifecycle: Added C++20 (`-std=c++20`) + Boost (Asio, Serialization), OpenSSL (SHA-256 via EVP), nlohmann/json (vendored `src/json.hpp`)
 
 
 <!-- MANUAL ADDITIONS START -->

.gitignore

@@ -112,3 +112,7 @@ Thumbs.db
 # Misc
 node_modules/
 tests/cli_tests
+node1
+node2
+*.pem
+*.srl

.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/013-ci-cd-pipeline"
+  "feature_directory": "specs/014-documentation-developer-guide"
 }

README

@@ -1 +1,175 @@
 # metaverse-systems/blockchain
+
+A C++ blockchain node for storing and replicating data in a tamper-resistant way. Key capabilities:
+
+- **Proof-of-Work consensus** with automatic difficulty adjustment
+- **P2P networking** with peer discovery, gossip exchange, and block propagation
+- **Stream-based data model** — publish structured key/value entries to named streams
+- **Merkle proofs** for O(log n) block inclusion verification
+- **TLS everywhere** — both JSON-RPC and P2P interfaces require TLS
+- **Cross-platform** — builds on Linux, macOS, and Windows (MSYS2)
+
+## Build Prerequisites
+
+| Dependency | Minimum Version | Purpose |
+|-----------|----------------|---------|
+| GCC | 14 | C++20 compiler (Linux) |
+| Clang | 18 | C++20 compiler (Linux/macOS) |
+| Boost | — | Asio (networking), Serialization (persistence) |
+| OpenSSL | 3.x | SHA-256, TLS, certificate generation |
+| Catch2 | 3.x | Test framework |
+| Autotools | — | Build system (autoconf, automake, autoconf-archive, libtool, pkg-config) |
+
+## Build Instructions
+
+### Linux (Ubuntu/Debian)
+
+```bash
+sudo apt-get update
+sudo apt-get install -y autoconf-archive pkg-config \
+  libboost-serialization-dev libboost-program-options-dev \
+  libssl-dev catch2
+
+autoreconf -fi
+./configure
+make
+```
+
+### macOS
+
+```bash
+brew install boost openssl@3 catch2 autoconf automake autoconf-archive libtool pkg-config
+
+export PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig:$PKG_CONFIG_PATH"
+export LDFLAGS="-L$(brew --prefix boost)/lib $LDFLAGS"
+export CPPFLAGS="-I$(brew --prefix boost)/include $CPPFLAGS"
+
+autoreconf -fi
+./configure
+make
+```
+
+### Windows (MSYS2 UCRT64)
+
+```bash
+pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-boost \
+  mingw-w64-ucrt-x86_64-openssl mingw-w64-ucrt-x86_64-cmake \
+  autotools autoconf-archive make pkg-config git
+
+# Build Catch2 from source (not available via pacman)
+git clone --depth 1 --branch v3.4.0 https://github.com/catchorg/Catch2.git /tmp/catch2
+cmake -S /tmp/catch2 -B /tmp/catch2/build -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=$MINGW_PREFIX
+cmake --build /tmp/catch2/build -j8
+cmake --install /tmp/catch2/build
+
+autoreconf -fi
+./configure --with-boost-libdir=$MINGW_PREFIX/lib
+make
+```
+
+## Quickstart: Two-Node Network
+
+This walkthrough starts two connected blockchain nodes, publishes a stream entry on one, and verifies it propagates to the other.
+
+### 1. Create Blockchain Directories
+
+```bash
+mkdir -p node1 node2
+```
+
+### 2. Generate TLS Certificates
+
+Both RPC and P2P connections require TLS. Generate a shared CA and per-node certificates directly in each directory:
+
+```bash
+# Generate CA key and certificate
+openssl genpkey -algorithm RSA -out ca-key.pem -pkeyopt rsa_keygen_bits:2048
+openssl req -new -x509 -key ca-key.pem -out ca.pem -days 365 -subj "/CN=Blockchain CA"
+
+# Generate key and certificate for node 1
+openssl genpkey -algorithm RSA -out node1/key.pem -pkeyopt rsa_keygen_bits:2048
+openssl req -new -key node1/key.pem -out node1/node.csr -subj "/CN=localhost"
+openssl x509 -req -in node1/node.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
+  -out node1/cert.pem -days 365
+cp ca.pem node1/ca.pem
+
+# Generate key and certificate for node 2
+openssl genpkey -algorithm RSA -out node2/key.pem -pkeyopt rsa_keygen_bits:2048
+openssl req -new -key node2/key.pem -out node2/node.csr -subj "/CN=localhost"
+openssl x509 -req -in node2/node.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
+  -out node2/cert.pem -days 365
+cp ca.pem node2/ca.pem
+```
+
+See [docs/configuration.md](docs/configuration.md#tls-setup) for a full TLS reference.
+
+### 3. Generate Configuration Files
+
+```bash
+./src/blockchain --generate-config node1
+./src/blockchain --generate-config node2
+```
+
+Edit `node1/config.json` — use the defaults (RPC 12345, P2P 12346).
+
+Edit `node2/config.json` — change the ports so both nodes can run on the same machine:
+
+```json
+{
+  "network": {
+    "rpc_port": 12347,
+    "p2p_port": 12348
+  }
+}
+```
+
+### 4. Start Both Nodes
+
+```bash
+# Terminal 1
+./src/blockchain node1
+
+# Terminal 2
+./src/blockchain node2
+```
+
+### 5. Connect the Nodes
+
+Tell node 2 to connect to node 1's P2P port:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"addPeer","params":{"host":"127.0.0.1","port":12346}}' | \
+  openssl s_client -connect localhost:12347 -CAfile ca.pem -quiet 2>/dev/null
+```
+
+### 6. Publish a Stream Entry
+
+Publish data on node 1:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"publish","params":{"stream":"test","key":"hello","data":"world"}}' | \
+  openssl s_client -connect localhost:12345 -CAfile ca.pem -quiet 2>/dev/null
+```
+
+### 7. Verify Propagation
+
+Query node 2 to confirm the entry arrived:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"getStreamEntries","params":{"stream":"test"}}' | \
+  openssl s_client -connect localhost:12347 -CAfile ca.pem -quiet 2>/dev/null
+```
+
+You should see the `hello`/`world` entry in the response.
+
+## Documentation
+
+- [Configuration Reference](docs/configuration.md) — CLI flags, config.json schema, TLS setup
+- [RPC API Reference](docs/rpc-api.md) — all 20 JSON-RPC methods with examples
+- [Architecture Overview](docs/architecture.md) — subsystem overview and data flow diagrams
+- [Contributing Guide](docs/contributing.md) — building, testing, coding conventions, PR workflow
+- [Roadmap](docs/ROADMAP.md) — completed and planned features
+
+## License
+
+This project is licensed under the MIT License. See [COPYING](COPYING) for details.

docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-Last updated: 2026-04-11
+Last updated: 2026-04-12
 
 ## Completed
 
@@ -18,6 +18,8 @@ Last updated: 2026-04-11
 | 010  | RPC API Expansion | Four new JSON-RPC methods: `getNodeStatus` (comprehensive health snapshot), `getBlockRange` (batch block retrieval with 1000-block cap and optional headers-only mode), `getChainLength`, `getChunkCount`; read-only endpoints with no transport-layer changes |
 | 011  | Graceful Multi-Chunk Shutdown & Startup | Per-chunk dirty tracking, block ingestion freeze on SIGINT/SIGTERM, dirty-aware saveAllChunks, full-chain recovery with validation and cross-chunk linkage checks, index rebuild from chunks, `fast_startup` config option |
 | 012  | Integration Test Suite | End-to-end Catch2 integration tests over real TLS: 19 RPC endpoint tests (all JSON-RPC methods with positive/negative cases), 3 P2P tests (single-block propagation, multi-block propagation, 3-node relay), shared test infrastructure (TLS cert generation, in-process NodeInstance, synchronous RpcTestClient), bug fixes in BlockPropagation consensus config and PeerClient read loop |
+| 013  | CI/CD Pipeline | GitHub Actions workflow with matrix build (Linux GCC/Clang, macOS Clang, Windows MSYS2), per-binary test execution, MSYS2 caching, Catch2-from-source on Windows |
+| 014  | Documentation & Developer Guide | Expanded README with cross-platform build instructions and two-node quickstart, configuration reference (9 CLI flags, 30 config.json fields, TLS setup), RPC API reference (20 methods with curl examples), architecture overview with Mermaid diagrams, contributing guide |
 
 ## Suggested Specs
 
@@ -53,17 +55,13 @@ The daemon takes a single positional argument (blockchain directory). Ports are
 
 #### 013 — CI/CD Pipeline
 
-No CI configuration exists. The constitution requires cross-platform support (Linux, macOS, Windows) but there is no automated verification. Add CI for all three platforms.
-
-**Scope**: GitHub Actions workflow, matrix build (Linux gcc/clang, macOS clang, Windows MSVC), `make check` on all platforms, artifact caching for Boost/OpenSSL.
+*Completed. See spec 013 in Completed table above.*
 
 ---
 
 #### 014 — Documentation & Developer Guide
 
-`README.md` contains a single heading. The quickstart and contract docs exist in the spec directory but are not surfaced to developers. Write user-facing documentation.
-
-**Scope**: README with build instructions, architecture overview, configuration guide, RPC API reference, contributing guide.
+*Completed. See spec 014 in Completed table above.*
 
 ---
 
@@ -101,9 +99,9 @@ No way to verify block inclusion without downloading the full chain. Design a li
 010 RPC Expansion ──────┼── Tier 3: COMPLETE ✓
 011 Graceful Lifecycle ─┘
 012 Integration Tests ──┐
-013 CI/CD Pipeline ─────┼── Tier 4: quality
+013 CI/CD Pipeline ─────┼── Tier 4: COMPLETE ✓
 014 Documentation ──────┘
 015–017 ────────────────── Tier 5: future
 ```
 
-Tiers 1, 2, and 3 are complete. Tier 4 specs (012–014) are independent and can proceed as the next priority.
+Tiers 1–4 are complete. Tier 5 specs (015–017) are exploratory future work.