some doc updates, version bump,

Author: Hendler

.github/workflows/release-crate.yml

@@ -45,6 +45,12 @@ jobs:
 
       - uses: actions-rust-lang/setup-rust-toolchain@v1
 
+      - name: Pre-publish compile check (all crates)
+        run: |
+          echo "Checking all publishable crates compile cleanly with -D warnings..."
+          cargo check -p jacs -p jacs-binding-core -p jacs-mcp -p jacs-cli
+          echo "All crates compile cleanly"
+
       - name: Publish jacs to crates.io
         run: |
           LATEST=$(curl -sL --retry 3 --retry-delay 5 -H 'User-Agent: jacs-ci (https://github.com/HumanAssisted/JACS)' https://crates.io/api/v1/crates/jacs | python3 -c "import sys,json; print(json.load(sys.stdin)['crate']['max_version'])" 2>/dev/null || echo "")

AGENTS.md

@@ -2,16 +2,49 @@ Welcome.
 
 You may use the top level Cargo.toml to understand the repo.
 jacs/ is the directory with the core library.
-./jacspy is the python wrapper with  functionality for integrations
-./jacsnpm is the npm/node wrapper with  functionality for integrations
+./jacspy is the python wrapper with functionality for integrations
+./jacsnpm is the npm/node wrapper with functionality for integrations
 
 Look for examples in tests for how to use the library.
 README.md and CHANGELOG.md may be useful to understand some future goals and what has been done.
 
+## Releasing
+
+See **[RELEASING.md](./RELEASING.md)** for the complete release process, including
+the full file checklist, tag-based CI workflow, and troubleshooting failed releases.
+
 ## Version Bump Checklist
 
 When bumping the JACS version, **all** of the following locations must be updated to the same version. The publish order matters — crates.io requires dependencies to be published before dependents.
 
+### Makefile commands
+
+```bash
+make versions        # show all detected versions from source files
+make check-versions  # fail if any main-track versions don't match
+
+# Pre-publish compile check (catches -D warnings failures before publish)
+RUSTFLAGS="-D warnings" cargo check -p jacs -p jacs-binding-core -p jacs-mcp -p jacs-cli
+
+# CI-triggered releases (via git tags)
+make release-jacs          # crates.io (jacs, binding-core, jacs-mcp, jacs-cli)
+make release-jacspy        # PyPI
+make release-jacsnpm       # npm
+make release-cli           # GitHub Release binaries
+make release-jacs-storage  # storage backend crates
+make release-everything    # all of the above
+
+# Retry failed releases (deletes tag, retags, pushes)
+make retry-jacspy
+make retry-jacsnpm
+make retry-cli
+
+# Local publish (requires credentials)
+make publish-jacs          # all Rust crates in dependency order
+make publish-jacspy        # PyPI
+make publish-jacsnpm       # npm
+```
+
 ### Publish Order (crates.io)
 
 Crates must be published in this order with ~30s delays between each for crates.io indexing:
@@ -21,7 +54,7 @@ Crates must be published in this order with ~30s delays between each for crates.
 3. `jacs-mcp` (depends on `jacs` + `jacs-binding-core`)
 4. `jacs-cli` (depends on `jacs` + `jacs-mcp`)
 
-Use `make publish-jacs` for local publish or `make release-jacs` for CI-triggered publish.
+The CI workflow (`release-crate.yml`) and `make publish-jacs` handle this order automatically.
 
 ### JACS Repo — Cargo.toml files (package version)
 
@@ -45,6 +78,19 @@ Use `make publish-jacs` for local publish or `make release-jacs` for CI-triggere
 | `jacs-cli/Cargo.toml` | `jacs = { version = "X.Y.Z", path = ... }` |
 | `jacs-cli/Cargo.toml` | `jacs-mcp = { version = "X.Y.Z", path = ... }` |
 
+### Storage backend crates
+
+These have their own version track (e.g. `0.1.0`). Bump their package `version`
+only when they have actual changes. **Always** keep their `jacs` dependency
+version in sync with the main release.
+
+| File | Fields |
+|------|--------|
+| `jacs-duckdb/Cargo.toml` | `version` (own track), `jacs = { version = "X.Y.Z" }` |
+| `jacs-redb/Cargo.toml` | `version` (own track), `jacs = { version = "X.Y.Z" }` |
+| `jacs-surrealdb/Cargo.toml` | `version` (own track), `jacs = { version = "X.Y.Z" }` |
+| `jacs-postgresql/Cargo.toml` | `version` (own track), `jacs = { version = "X.Y.Z" }` |
+
 ### JACS Repo — Non-Rust package manifests
 
 | File | Field |
@@ -65,6 +111,7 @@ Use `make publish-jacs` for local publish or `make release-jacs` for CI-triggere
 | `README.md` | Footer version line |
 | `jacs/README.md` | Footer version line |
 | `jacs-cli/README.md` | Footer version line |
+| `CHANGELOG.md` | Add new `## X.Y.Z` section at top |
 
 ### haisdk Repo — JACS version pins
 
@@ -83,13 +130,16 @@ After bumping, verify with:
 
 ```bash
 # Check all JACS versions match
-make versions
+make check-versions
+
+# Verify workspace compiles cleanly (same flags as CI)
+RUSTFLAGS="-D warnings" cargo check -p jacs -p jacs-binding-core -p jacs-mcp -p jacs-cli
 
-# Verify workspace compiles
-cargo check --workspace
+# Regenerate lockfile
+cargo generate-lockfile
 
 # Run tests
-make test
+make test-rust-pr
 ```
 
 ## Install Commands

CHANGELOG.md

@@ -1,9 +1,15 @@
-## 0.9.5
+## 0.9.6
 
 ### Fixes
 
+- Fix jacs-cli publish failure: remove unused `SimpleAgent` imports that caused `-D warnings` compile errors in CI
+- Fix crates.io release workflow: add explicit `cargo check -D warnings` step before publish so compile failures are caught early
 - Include `deprecation.js` and `deprecation.d.ts` in npm package bundle (was missing from `files` in package.json)
 
+### Docs
+
+- Add `RELEASING.md` with complete version bump checklist and release process
+
 ## 0.9.4
 
 ### API and core

README.md

@@ -234,4 +234,4 @@ Framework adapters for signing AI outputs with zero infrastructure:
 
 ---
 
-v0.9.5 | [Apache-2.0 OR MIT](./LICENSE-APACHE) | [Third-Party Notices](./THIRD-PARTY-NOTICES)
+v0.9.6 | [Apache-2.0 OR MIT](./LICENSE-APACHE) | [Third-Party Notices](./THIRD-PARTY-NOTICES)

RELEASING.md

@@ -0,0 +1,117 @@
+# Releasing JACS
+
+## Files to update when bumping versions
+
+All main crates share a single version (e.g. `0.9.6`). Storage backend crates
+(`jacs-duckdb`, `jacs-redb`, `jacs-surrealdb`, `jacs-postgresql`) have their
+own version track but their `jacs` dependency version must match the main version.
+
+### Package versions (the `version = "X.Y.Z"` line)
+
+| File | Field |
+|------|-------|
+| `jacs/Cargo.toml` | `version` |
+| `binding-core/Cargo.toml` | `version` |
+| `jacs-cli/Cargo.toml` | `version` |
+| `jacs-mcp/Cargo.toml` | `version` |
+| `jacsnpm/Cargo.toml` | `version` |
+| `jacspy/Cargo.toml` | `version` |
+| `jacsgo/lib/Cargo.toml` | `version` |
+| `jacsnpm/package.json` | `"version"` |
+| `jacspy/pyproject.toml` | `version` |
+| `jacs-mcp/contract/jacs-mcp-contract.json` | `"version"` |
+
+### Inter-crate dependency versions
+
+| File | Dependency |
+|------|-----------|
+| `binding-core/Cargo.toml` | `jacs = { version = "..." }` |
+| `jacs-cli/Cargo.toml` | `jacs = { version = "..." }` |
+| `jacs-cli/Cargo.toml` | `jacs-mcp = { version = "..." }` |
+| `jacs-mcp/Cargo.toml` | `jacs = { version = "..." }` |
+| `jacs-mcp/Cargo.toml` | `jacs-binding-core = { version = "..." }` |
+| `jacs-duckdb/Cargo.toml` | `jacs = { version = "..." }` |
+| `jacs-redb/Cargo.toml` | `jacs = { version = "..." }` |
+| `jacs-surrealdb/Cargo.toml` | `jacs = { version = "..." }` |
+| `jacs-postgresql/Cargo.toml` | `jacs = { version = "..." }` |
+
+### Documentation version references
+
+| File | Line pattern |
+|------|-------------|
+| `README.md` | `vX.Y.Z \| [Apache-2.0 ...` |
+| `jacs/README.md` | `**Version**: X.Y.Z \| ...` |
+| `jacs-cli/README.md` | `vX.Y.Z \| [Apache 2.0 ...` |
+| `CHANGELOG.md` | Add new `## X.Y.Z` section at top |
+
+## Quick version check
+
+```bash
+make versions        # show all detected versions
+make check-versions  # fail if versions don't match
+```
+
+## Release process
+
+### 1. Bump versions
+
+Update all files listed above. Then verify:
+
+```bash
+make check-versions
+cargo generate-lockfile
+RUSTFLAGS="-D warnings" cargo check -p jacs -p jacs-binding-core -p jacs-mcp -p jacs-cli
+```
+
+### 2. Commit and push
+
+```bash
+git add -A
+git commit -m "Bump version to X.Y.Z"
+git push
+```
+
+### 3. Release via tags
+
+Release all registries (crates.io + PyPI + npm) plus CLI binaries:
+
+```bash
+make release-everything
+```
+
+Or release individually:
+
+```bash
+make release-jacs       # crates.io (jacs, binding-core, jacs-mcp, jacs-cli)
+make release-jacspy     # PyPI
+make release-jacsnpm    # npm
+make release-cli        # GitHub Release binaries
+make release-jacs-storage  # storage backend crates
+```
+
+### 4. Verify
+
+Check each registry:
+- https://crates.io/crates/jacs
+- https://crates.io/crates/jacs-cli
+- https://crates.io/crates/jacs-binding-core
+- https://crates.io/crates/jacs-mcp
+- https://pypi.org/project/jacs/
+- https://www.npmjs.com/package/@hai.ai/jacs
+
+### Retrying failed releases
+
+```bash
+make retry-jacspy      # delete tag, retag, push
+make retry-jacsnpm
+make retry-cli
+```
+
+For crates.io, if a crate already published but a later one failed, just re-run
+`make release-jacs` — the workflow skips already-published crates.
+
+### Storage backend crates
+
+These have independent version tracks. Bump their `version` field only when
+they have actual changes. Always keep their `jacs` dependency version in sync
+with the main release version.

binding-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jacs-binding-core"
-version = "0.9.5"
+version = "0.9.6"
 edition = "2024"
 rust-version = "1.93"
 resolver = "3"
@@ -19,7 +19,7 @@ attestation = ["jacs/attestation"]
 pq-tests = []
 
 [dependencies]
-jacs = { version = "0.9.5", path = "../jacs" }
+jacs = { version = "0.9.6", path = "../jacs" }
 serde_json = "1.0"
 base64 = "0.22.1"
 serde = { version = "1.0", features = ["derive"] }

jacs-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jacs-cli"
-version = "0.9.5"
+version = "0.9.6"
 edition = "2024"
 rust-version = "1.93"
 description = "JACS CLI: command-line interface for JSON AI Communication Standard"
@@ -22,8 +22,8 @@ mcp = ["dep:jacs-mcp"]
 attestation = ["jacs/attestation"]
 
 [dependencies]
-jacs = { version = "0.9.5", path = "../jacs" }
-jacs-mcp = { version = "0.9.5", path = "../jacs-mcp", features = ["mcp", "full-tools"], optional = true }
+jacs = { version = "0.9.6", path = "../jacs" }
+jacs-mcp = { version = "0.9.6", path = "../jacs-mcp", features = ["mcp", "full-tools"], optional = true }
 clap = { version = "4.5.4", features = ["derive", "cargo"] }
 rpassword = "7.3.1"
 reqwest = { version = "0.13.2", default-features = false, features = ["blocking", "json", "rustls"] }

jacs-cli/README.md

@@ -71,4 +71,4 @@ The MCP server uses stdio transport only (no HTTP) for security.
 - [MCP Integration](https://humanassisted.github.io/JACS/integrations/mcp.html)
 - [JACS core library on crates.io](https://crates.io/crates/jacs)
 
-v0.9.5 | [Apache 2.0 with Common Clause](../LICENSE)
+v0.9.6 | [Apache 2.0 with Common Clause](../LICENSE)

jacs-cli/src/main.rs

@@ -1742,8 +1742,6 @@ pub fn main() -> Result<(), Box<dyn Error>> {
                 }
             }
             Some(("serve", serve_matches)) => {
-                use jacs::simple::SimpleAgent;
-
                 let port = *serve_matches.get_one::<u16>("port").unwrap();
                 let host = serve_matches
                     .get_one::<String>("host")
@@ -1835,8 +1833,6 @@ pub fn main() -> Result<(), Box<dyn Error>> {
                 }
             }
             Some(("quickstart", qs_matches)) => {
-                use jacs::simple::SimpleAgent;
-
                 let port = *qs_matches.get_one::<u16>("port").unwrap();
                 let host = qs_matches
                     .get_one::<String>("host")
@@ -1950,8 +1946,6 @@ pub fn main() -> Result<(), Box<dyn Error>> {
             _ => println!("please enter subcommand see jacs a2a --help"),
         },
         Some(("quickstart", qs_matches)) => {
-            use jacs::simple::SimpleAgent;
-
             let algorithm = qs_matches
                 .get_one::<String>("algorithm")
                 .map(|s| s.as_str());
@@ -2255,7 +2249,7 @@ pub fn main() -> Result<(), Box<dyn Error>> {
                         process::exit(1);
                     });
 
-                    let (agent, _info) = SimpleAgent::ephemeral(Some("ring-Ed25519"))
+                    let (_agent, _info) = SimpleAgent::ephemeral(Some("ring-Ed25519"))
                         .unwrap_or_else(|e| {
                             eprintln!("Failed to create agent: {}", e);
                             process::exit(1);

jacs-duckdb/Cargo.toml

@@ -13,7 +13,7 @@ keywords = ["cryptography", "json", "duckdb", "storage"]
 categories = ["database", "data-structures"]
 
 [dependencies]
-jacs = { version = "0.9.5", path = "../jacs", default-features = false }
+jacs = { version = "0.9.6", path = "../jacs", default-features = false }
 duckdb = { version = "1.4", features = ["bundled", "json"] }
 serde_json = "1.0"