knowledge

Author: Hendler

rust/haiai/docs/knowledge/haiai-guides/agents.md

@@ -130,7 +130,7 @@ If you add a tool to MCP but not CLI (or vice versa), you must add it to the app
 Each SDK pins a published JACS version for CI/release, but supports local path overrides for development:
 
 - **Node:** `npm run deps:local` switches `@hai.ai/jacs` to `file:../../JACS/jacsnpm`. Use `npm run deps:prod` to switch back. The committed `package.json` must always use the published version.
-- **Rust:** Uncomment the `[patch.crates-io]` block in `rust/Cargo.toml` to build against `../../JACS/`. Must be commented out before publish.
+- **Rust:** Uncomment the `[patch.crates-io]` block in `rust/Cargo.toml` to build against `../../JACS/`. Must be commented out before publish. Building with the patch block (even temporarily) adds `[[patch.unused]]` entries to `rust/Cargo.lock` — the git clean filter in `.gitattributes` strips these automatically on staging. **First-time setup:** run `git config filter.clean-cargo-lock.clean 'sed "/^\[\[patch\.unused\]\]/,/^$/d"'` and `git config filter.clean-cargo-lock.smudge cat` to activate the filter.
 - **Python:** Pin in `pyproject.toml` (`jacs==X.Y.Z`). For local dev, use `pip install -e ../../JACS/jacspy` (or equivalent) to shadow the published version.
 
 `make check-jacs-versions` verifies all SDKs agree on the published JACS version.

rust/haiai/docs/knowledge/haiai-sdk/hai-mcp.md

@@ -74,7 +74,7 @@ The server adds these tools on top of the base JACS MCP tools:
 | Tool | Description |
 |------|-------------|
 | `hai_create_agent` | Create a new JACS agent locally |
-| `hai_register_agent` | Register with HAI platform (accepts registration_key) |
+| `hai_register_agent` | Register with HAI platform |
 | `hai_hello` | Authenticated handshake |
 | `hai_agent_status` | Agent verification status |
 | `hai_verify_status` | Verification status lookup |

rust/haiai/docs/knowledge/haiai-sdk/haiai-cli.md

@@ -41,13 +41,7 @@ Options:
 | `--key-dir` | `./jacs_keys` | Key storage directory |
 | `--config-path` | `./jacs.config.json` | Config file path |
 
-### 2. Register and get your email address
-
-```bash
-haiai init --name myagent --key YOUR_REGISTRATION_KEY
-```
-
-Get your registration key from the [dashboard](https://hai.ai/dashboard). Your agent now has the address `myagent@hai.ai`.
+Registration happens during `init` (see step 1). Your agent gets `myagent@hai.ai` automatically.
 
 ### 3. Send and receive email
 
@@ -112,6 +106,11 @@ Connect it to any MCP client (Claude Desktop, Cursor, Claude Code, etc.):
 | `list-contacts` | List contacts from email history |
 | `email-status` | Account status and limits |
 
+**Username**
+
+| Command | Description |
+|---------|-------------|
+
 **Benchmarking**
 
 | Command | Description |

rust/haiai/docs/knowledge/haiai-sdk/root.md

@@ -21,29 +21,37 @@ brew install haiai
 cargo install haiai-cli
 ```
 
-This gives you the `haiai` binary — CLI and MCP server in one.
-
-## Quickstart
+### Shell script
 
-### 1. Create an agent identity
+No package manager? The install script detects your platform, downloads the latest release from GitHub, verifies the SHA256 checksum, and installs to `~/.haiai/bin`. Handles upgrades and downgrades.
 
 ```bash
-export JACS_PRIVATE_KEY_PASSWORD='your-password'
+curl -fsSL https://raw.githubusercontent.com/HumanAssisted/haiai/main/install.sh | sh
+```
 
-haiai init \
-  --name my-agent \
-  --domain example.com
+Pin a version or change the install directory:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/HumanAssisted/haiai/main/install.sh | sh -s -- --version 0.2.1
+curl -fsSL https://raw.githubusercontent.com/HumanAssisted/haiai/main/install.sh | sh -s -- --dir /usr/local/bin
 ```
 
-This generates a JACS keypair and config. No separate install needed.
+Works on macOS (Intel & Apple Silicon) and Linux (x64 & ARM64).
 
-### 2. Register and get your email address
+This gives you the `haiai` binary — CLI and MCP server in one.
+
+## Quickstart
+
+### 1. Create an agent identity
 
 ```bash
+export JACS_PRIVATE_KEY_PASSWORD='your-password'
+
 haiai init --name myagent --key YOUR_REGISTRATION_KEY
 ```
 
-Get your registration key from the [dashboard](https://hai.ai/dashboard) after reserving your username. Your agent now has the address `myagent@hai.ai`.
+This generates a JACS keypair, registers with HAI, and assigns `myagent@hai.ai`.
+Get your registration key from the [dashboard](https://hai.ai/dashboard) after reserving a username.
 
 ### 3. Send and receive email
 
@@ -80,7 +88,7 @@ Your AI agent now has access to all HAI tools — identity, email, signing, and
 | Category | Tools |
 |----------|-------|
 | **Email** | Send, reply, forward, search, list, read/unread, delete, contacts, quota status |
-| **Identity** | Create agent, register, claim username, check status, verify |
+| **Identity** | Create agent, register, check status, verify |
 | **Signing** | Sign and verify any JSON document or file with JACS |
 | **Documents** | Store, retrieve, search, and manage signed documents |
 
@@ -106,9 +114,9 @@ export JACS_KEYCHAIN_BACKEND=disabled
 haiai mcp
 ```
 
-## Native language bindings (pre-alpha)
+## Native language bindings (beta)
 
-Native SDKs for Python, Node.js, and Go are available on npm, pypi, and here but are **pre-alpha** — APIs may change. The MCP server is the recommended integration path.
+Native SDKs for Python, Node.js, and Go are available on npm, pypi, and here and are in **beta** — APIs may change. The MCP server is the recommended integration path.
 
 ```bash
 pip install haiai              # Python

rust/haiai/docs/knowledge/jacs/README.md

@@ -136,4 +136,4 @@ Report vulnerabilities to security@hai.ai. Do not open public issues for securit
 
 ---
 
-v0.9.7 | [Apache-2.0 OR MIT](./LICENSE-APACHE) | [Third-Party Notices](./THIRD-PARTY-NOTICES)
+v0.9.7 | [Apache-2.0](./LICENSE-APACHE) | [Third-Party Notices](./THIRD-PARTY-NOTICES)

rust/haiai/docs/knowledge/jacsbook/advanced/key-rotation.md

@@ -136,24 +136,88 @@ This signed message:
 - Provides an audit trail
 - Binds old and new keys together cryptographically
 
-### CLI Commands (Planned)
-
-> **Note**: These CLI commands are planned for a future release. Currently, key rotation must be performed programmatically using the Rust API.
+### CLI Commands
 
 ```bash
-# Rotate keys with default algorithm (Coming Soon)
+# Rotate keys with default algorithm
 jacs agent rotate-keys
 
-# Rotate to post-quantum algorithm (Coming Soon)
+# Rotate to post-quantum algorithm
 jacs agent rotate-keys --algorithm pq2025
 
-# List key history (Coming Soon)
-jacs agent keys list
+# List key history (active and archived keys)
+jacs agent keys-list
+
+# Repair config after a crash during rotation
+jacs agent repair
 
 # Revoke a compromised key (Coming Soon)
 jacs agent keys revoke <key-hash>
 ```
 
+### Transition Signature
+
+During key rotation, JACS produces a cryptographic transition proof that binds the old key to the new key. This proof is embedded in the agent document as `jacsKeyRotationProof`:
+
+```json
+{
+  "jacsKeyRotationProof": {
+    "transitionMessage": "JACS_KEY_ROTATION:{agent_id}:{old_key_hash}:{new_key_hash}:{timestamp}",
+    "signature": "base64-encoded-signature-with-old-key",
+    "signingAlgorithm": "ring-Ed25519",
+    "oldPublicKeyHash": "sha256-of-old-key",
+    "newPublicKeyHash": "sha256-of-new-key",
+    "timestamp": "2026-04-07T10:00:00Z"
+  }
+}
+```
+
+The transition message is signed with the **old** private key before it is archived. This proves:
+- The rotation was authorized by the holder of the previous key
+- The old and new keys are cryptographically linked
+- An attacker cannot forge a rotation without the old private key
+
+You can verify a transition proof programmatically using `Agent::verify_transition_proof()`.
+
+### Crash Recovery
+
+JACS uses a write-ahead journal to recover from crashes during key rotation. Before rotation begins, a journal file is written to `{key_directory}/.jacs_rotation_journal.json`. The journal tracks the rotation stage:
+
+1. `started` - Rotation initiated
+2. `keys_rotated` - New keys generated, old keys archived
+3. `agent_saved` - New agent version saved to disk
+4. `config_signed` - Config re-signed with new key (journal deleted on success)
+
+If the process crashes mid-rotation, the next agent load detects the journal and automatically repairs the config by re-signing it with the current key. No manual intervention is required for the common case.
+
+For manual recovery: `jacs agent repair`
+
+### Cross-Algorithm Rotation
+
+You can change the signing algorithm during rotation:
+
+```bash
+# Rotate from Ed25519 to post-quantum
+jacs agent rotate-keys --algorithm pq2025
+```
+
+```rust
+// Rust API
+let result = advanced::rotate(&agent, Some("pq2025"))?;
+```
+
+```python
+# Python
+result = client.rotate_keys(algorithm="pq2025")
+```
+
+```typescript
+// Node.js
+const result = await client.rotateKeys({ algorithm: 'pq2025' });
+```
+
+After cross-algorithm rotation, the config file's `jacs_agent_key_algorithm` field is updated atomically. Documents signed before the rotation remain verifiable using the archived old key.
+
 ### Example Rotation Flow
 
 ```