Add a justfile for build & test automation

.github/workflows/ci_python.yml

@@ -43,6 +43,11 @@ jobs:
         with:
           shared-key: fabric-rust
 
+      - name: Install just
+        uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6
+        with:
+          tool: just@1.50.0
+
       - name: Set up uv
         uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
 
@@ -51,7 +56,7 @@ jobs:
       - name: Build SDK with native extension
         run: |
           uv venv --python 3.12 .venv
-          uv pip install --python .venv/bin/python -e . "pyyaml>=6"
+          uv sync --group test --no-group dev --extra harbor --extra hermes --extra relay
 
       # Dependency-free smokes only: the gated integration smokes
       # (smoke_hermes_sdk, smoke_relay_integration, and the Docker-backed
@@ -86,5 +91,4 @@ jobs:
       - name: Run pytest
         run: |
           set -euo pipefail
-          uv sync --group test --no-group dev --extra harbor --extra hermes --extra relay
-          uv run pytest
+          just test-python

.github/workflows/ci_rust.yml

@@ -33,6 +33,11 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Install just
+        uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6
+        with:
+          tool: just@1.50.0
+
       - name: Set up Rust
         uses: actions-rust-lang/setup-rust-toolchain@150fca883cd4034361b621bd4e6a9d34e5143606 # v1.15.4
         with:
@@ -54,4 +59,4 @@ jobs:
       # Includes the schema snapshot tests, which guard the public contract
       # against drift from the Rust types.
       - name: Run workspace tests
-        run: cargo test --workspace --locked
+        run: just test-rust

.github/workflows/fern-docs.yml

@@ -31,6 +31,11 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Install just
+        uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6
+        with:
+          tool: just@1.50.0
+
       - name: Set up uv
         uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
 
@@ -42,32 +47,22 @@ jobs:
           toolchain: stable
           cache: false
 
-      # The Python reference is generated from the SDK docstrings (lazydocs) and
-      # the Rust reference from rustdoc (cargo doc --no-deps -p fabric-core),
-      # so the published docs never drift from the code.
-      - name: Generate API reference (Python docstrings + Rust rustdoc)
-        run: |
-          uv sync --extra docs
-          PATH="$PWD/.venv/bin:$PATH" bash scripts/generate_api_docs.sh
-          .venv/bin/python scripts/docs/generate_rust_library_reference.py
-
       - name: Set up Node
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
         with:
           node-version: "20"
 
-      - name: Install Fern CLI
-        run: npm install -g fern-api@5.37.10
-
-      - name: Validate docs config
-        run: fern check
+      # Generate the Python reference from SDK docstrings and the Rust reference
+      # from rustdoc, then validate the Fern configuration.
+      - name: Generate API references and validate docs
+        run: just docs
 
       # Publish to the (internal-by-default) Fern site on merge to main.
       - name: Publish docs
         if: github.ref_name == 'main'
         env:
           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
-        run: fern generate --docs
+        run: npx --prefix docs --no-install fern generate --docs
 
       # Build a preview deployment for the PR and capture its URL.
       - name: Preview docs
@@ -78,7 +73,7 @@ jobs:
         run: |
           set -euo pipefail
           pr_number="${GITHUB_REF_NAME#pull-request/}"
-          if output="$(fern generate --docs --preview --id "pull-request-${pr_number}" 2>&1)"; then
+          if output="$(npx --prefix docs --no-install fern generate --docs --preview --id "pull-request-${pr_number}" 2>&1)"; then
             fern_exit=0
           else
             fern_exit=$?

.gitignore

@@ -15,6 +15,7 @@ __pycache__/
 *.egg-info/
 dist/
 build/
+/docs/node_modules/
 
 examples/*/artifacts/
 tests/fixtures/*/artifacts/

README.md

@@ -57,15 +57,20 @@ Prerequisites:
 - Rust and Cargo
 - Python 3.10+ for Fabric
 - Python 3.11-3.13 for Hermes
+- `just` 1.50.0+
 - `NVIDIA_API_KEY` for NVIDIA-hosted model access
 
-Install Fabric and the `fabric` CLI:
-
+Install `just` if not already installed.
 ```bash
-python3 -m venv .tmp/fabric-venv
-.tmp/fabric-venv/bin/python -m pip install -e .
+cargo install just --locked
+```
+
+Refer to the [official installation guide](https://just.systems/man/en/installation.html) for more details.
 
-cargo install --path crates/fabric-cli --locked --force
+Install Fabric and the `fabric` CLI from the source checkout:
+
+```bash
+just build-all
 export PATH="$HOME/.cargo/bin:$PATH"
 ```
 
@@ -314,8 +319,8 @@ The opt-in real integration checks are `tests/smoke_hermes_session.py` and
 `start_session(...)` drive the core Fabric runtime lifecycle (`start_runtime` /
 `invoke_runtime` / `stop_runtime`) so one-shot and session paths use the same
 adapter execution contract. The CLI is a separate interface over the same Rust
-core. For source-tree development, install the package with
-`python3 -m pip install -e .` before using the SDK.
+core. For source-tree development, run `just build-python` before using the
+SDK.
 
 ## Harbor Integration
 

docs/getting-started/overview.mdx

@@ -64,12 +64,21 @@ request and the use of returned evidence.
 
 ## Quick start
 
+Install `just` 1.50.0+ if it is not already available.
+
+```bash
+cargo install just --locked
+```
+
+Refer to the [official installation guide](https://just.systems/man/en/installation.html)
+for more details.
+
 Install the Python SDK with its native binding and the CLI from a source
 checkout:
 
 ```bash
-python3 -m pip install -e .
-cargo install --path crates/fabric-cli --locked --force
+just build-all
+export PATH="$HOME/.cargo/bin:$PATH"
 ```
 
 Inspect and diagnose an agent package before running it:

docs/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "nemo-fabric-docs",
+  "private": true,
+  "version": "0.0.0",
+  "devDependencies": {
+    "fern-api": "5.37.10"
+  }
+}