diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 00000000..691c6aba
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,49 @@
+---
+name: bug report
+about: report a defect in the nest format, runtime, cli, or python bindings
+title: ''
+labels: bug
+assignees: ''
+---
+
+<!-- title in plain english, no Conventional Commits prefix. body explains what is broken and why it matters. -->
+
+## summary
+
+<!-- 1-3 sentences: what is broken. -->
+
+## reproduction
+
+<!-- minimal repro. paste the exact command, code, or .nest path. include input and any relevant flags. -->
+
+```
+$ nest <command> ...
+```
+
+## expected vs actual
+
+<!-- what should happen, then what actually happens. paste the actual error or output verbatim. -->
+
+- expected:
+- actual:
+
+## environment
+
+- nest version / commit:
+- os + arch:
+- rust toolchain (`rustc --version`):
+- python (`python3 --version`):
+- embedding model (if relevant):
+
+## scope
+
+- [ ] binary format / hash semantics
+- [ ] runtime / search contract
+- [ ] cli
+- [ ] python bindings
+- [ ] build / release tooling
+- [ ] docs only
+
+## additional context
+
+<!-- logs, related issues, prior ADRs, anything else. n/a if none. -->
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 00000000..07f1352d
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,40 @@
+---
+name: feature request
+about: propose a change to nest format, runtime, cli, python bindings, or docs
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+<!-- title in plain english, no Conventional Commits prefix. body explains the why; a future pr will show the what. -->
+
+## summary
+
+<!-- 1-3 sentences: what you want and the problem it solves. -->
+
+## scope
+
+- [ ] binary format / hash semantics
+- [ ] runtime / search contract
+- [ ] cli
+- [ ] python bindings
+- [ ] build / release tooling
+- [ ] docs only
+
+## proposal
+
+<!-- the shape of the change. api surface, cli flag, format field, etc. concrete is better than abstract. -->
+
+## alternatives
+
+<!-- what else you considered and why it falls short. n/a if none. -->
+
+## format / runtime impact
+
+<!-- if this touches binary layout, search contract, hash semantics, or model fingerprint, an ADR will be required under kdb/adr/. otherwise: n/a. -->
+
+n/a
+
+## additional context
+
+<!-- linked issues, prior PRs, ADRs, references. n/a if none. -->
diff --git a/.gitignore b/.gitignore
index d78d8876..75c96048 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,7 +5,8 @@
 *.so
 *.dylib
 *.dll
-
+kdb/
+adr/
 # Python
 __pycache__/
 *.py[cod]
diff --git a/AGENTS.md b/AGENTS.md
index fb27d5bb..b53845eb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -116,8 +116,7 @@ these are documented honest limitations of the current code, not bugs to silentl
 - `doc/architecture.md`: binary layout, API surface, errors, versioning, four hashes, SIMD dispatcher, search contract.
 - `doc/usage.md`: 10-section how-to for the 8 commands, presets, offline mode, citations.
 - `doc/changelog.md`: v0.1.0 and v0.2.0 deltas.
-- `doc/spec.md`: byte-by-byte format spec, the canonical reference for any external implementer.
-- `kdb/adr/`: 11 architectural decision records (0001 through 0011). every irreversible decision lives here.
+- `kdb/adr/`: architectural decisions records every product/feature/business irreversible decision lives here.
 - `database/README.md`: what each upstream PT-BR dataset is and how to rebuild the unified corpus.
 - `CONTRIBUTING.md`: external contributor flow.
 - `CODE_OF_CONDUCT.md`: contributor covenant 2.1, lowercase plain-style.
diff --git a/Cargo.toml b/Cargo.toml
index 55a74b39..22f01371 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -12,7 +12,7 @@ repository = "https://github.com/hoffresearch/nest"
 thiserror = "2"
 serde = { version = "1", features = ["derive"] }
 serde_json = { version = "1", features = ["preserve_order"] }
-sha2 = "0.10"
+sha2 = "0.11"
 memmap2 = "0.9"
 rayon = "1"
 clap = { version = "4", features = ["derive"] }
diff --git a/README.md b/README.md
index 83ce59e3..92ff0aaa 100644
--- a/README.md
+++ b/README.md
@@ -145,12 +145,12 @@ with `reproducible=True` (the script default) two operators get byte-identical `
 - `database/README.md` for what each upstream dataset is and how to rebuild the corpus
 - `doc/architecture.md` for binary layout, API surface, errors, versioning
 - `doc/usage.md` for the eight commands, presets, offline mode, citations
-- `doc/spec.md` for the byte-by-byte format
 - `kdb/adr/` for architectural decision records (0001 through 0011)
 - `doc/changelog.md` for v0.1 to v0.2 deltas
 
 ## license
 
-Made it simple, but signifcant. Brenner Cruvinel.
+made it simple, but signifcant. 
+Brenner Cruvinel.
 
 MIT.
diff --git a/crates/nest-cli/Cargo.toml b/crates/nest-cli/Cargo.toml
index 7c4eec29..3e6f21ba 100644
--- a/crates/nest-cli/Cargo.toml
+++ b/crates/nest-cli/Cargo.toml
@@ -16,5 +16,5 @@ anyhow = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 memmap2 = { workspace = true }
-rand = "0.9"
+rand = "0.10"
 hex = "0.4"
diff --git a/crates/nest-format/src/chunk.rs b/crates/nest-format/src/chunk.rs
index aa5de4f7..9623e2f1 100644
--- a/crates/nest-format/src/chunk.rs
+++ b/crates/nest-format/src/chunk.rs
@@ -55,7 +55,7 @@ pub fn chunk_id(
     h.update(byte_end.to_le_bytes());
     write_lp(&mut h, chunker_version.as_bytes());
     let digest = h.finalize();
-    format!("sha256:{:x}", digest)
+    format!("sha256:{}", hex::encode(digest))
 }
 
 fn write_lp(h: &mut Sha256, bytes: &[u8]) {
diff --git a/crates/nest-format/src/reader/decode.rs b/crates/nest-format/src/reader/decode.rs
index e3e50f89..d059fe57 100644
--- a/crates/nest-format/src/reader/decode.rs
+++ b/crates/nest-format/src/reader/decode.rs
@@ -40,7 +40,7 @@ impl<'a> NestView<'a> {
     pub fn file_hash_hex(&self) -> String {
         use sha2::{Digest, Sha256};
         let h = Sha256::digest(self.data);
-        format!("sha256:{:x}", h)
+        format!("sha256:{}", hex::encode(h))
     }
 
     /// `sha256:<hex>` of the canonical sections in the order fixed by spec
@@ -62,6 +62,6 @@ impl<'a> NestView<'a> {
             h.update((bytes.len() as u64).to_le_bytes());
             h.update(bytes.as_ref());
         }
-        Ok(format!("sha256:{:x}", h.finalize()))
+        Ok(format!("sha256:{}", hex::encode(h.finalize())))
     }
 }