docs(readme): add Documentation section linking every subdir README

Adds a dedicated "Documentation" section at the top of the root README
that explicitly enumerates SPEC.md, rust/README.md, nodejs/README.md, and
rust-sig-server/README.md with one-line descriptions, so readers landing
on the repo can find their way around without scrolling.

Also:
- Adds a "Sigchain storage server (optional)" quick-start block alongside
  the existing Rust and Node ones.
- Refreshes the test counts (rust: 81 → 99, nodejs: 72 → 91) to match the
  current suites.
- Updates the "What's not done yet" section: sigchain types, CLI, and
  storage server all exist now; the remaining gap is the verifier
  consulting the chain for revocations during verify id.
This commit is contained in:
Tudisco 2026-05-24 15:19:39 -06:00
parent d0db6f00f1
commit 636dd9a3a8

View File

@ -29,13 +29,30 @@ A separate [`rust-sig-server/`](rust-sig-server/) crate provides an optional
HTTP storage tier for sigchains — useful when a user doesn't want to set up HTTP storage tier for sigchains — useful when a user doesn't want to set up
DNS/hosting/nostr, but **never required**; the protocol stays decentralized. DNS/hosting/nostr, but **never required**; the protocol stays decentralized.
## Documentation
Start here:
- [**`SPEC.md`**](SPEC.md) — the language-agnostic protocol spec (v0.2).
Normative for every implementation.
- [**`rust/README.md`**](rust/README.md) — Rust implementation guide:
crate layout (`kez-core` / `kez-channels` / `kez-cli`), full CLI
reference, channel plugin model, library examples, and the gap list.
- [**`nodejs/README.md`**](nodejs/README.md) — Node/TypeScript port:
same shape as Rust, npm workspaces layout, crypto stack rationale,
CLI reference.
- [**`rust-sig-server/README.md`**](rust-sig-server/README.md) — the
optional storage server: API reference, no-auth design + threat
model, deployment recipes (bare-metal, Docker, PaaS), and how
channel-based publishing remains the fallback if the server is down.
## Quick start ## Quick start
### Rust ### Rust
```sh ```sh
cd rust cd rust
cargo build cargo build
cargo test # 81 tests cargo test # 99 tests
cargo run -p kez-cli -- verify id github:jason cargo run -p kez-cli -- verify id github:jason
``` ```
Full guide: [`rust/README.md`](rust/README.md). Full guide: [`rust/README.md`](rust/README.md).
@ -44,11 +61,19 @@ Full guide: [`rust/README.md`](rust/README.md).
```sh ```sh
cd nodejs cd nodejs
npm install npm install
npm test # 72 tests npm test # 91 tests
npm run cli -- verify id github:jason npm run cli -- verify id github:jason
``` ```
Full guide: [`nodejs/README.md`](nodejs/README.md). Full guide: [`nodejs/README.md`](nodejs/README.md).
### Sigchain storage server (optional)
```sh
cd rust-sig-server
cargo build --release
./target/release/kez-sig-server # listens on :7878
```
Full guide: [`rust-sig-server/README.md`](rust-sig-server/README.md).
## Cross-testing ## Cross-testing
```sh ```sh
@ -91,12 +116,18 @@ Pass `-v` for verbose output (echoes intermediate commands and proofs).
## What's not done yet ## What's not done yet
Tracked in both [`rust/README.md`](rust/README.md#whats-not-done-yet) and the Tracked in [`rust/README.md`](rust/README.md#whats-not-done-yet) and the
spec: spec:
- Sigchain walker (types exist; no append/walk/revoke flow yet). - **`verify id` consulting the sigchain.** Sigchain types, CLI commands
- `expires_at` enforcement during verify. (`kez sigchain add/revoke/show/export/publish`), and the storage server
- Typed `VerificationStatus.status` reflecting the five failure modes. all exist. But proof verification doesn't yet fetch the chain to check
for revocations — every `verify` is still a single one-shot proof check.
- `rotate` and `add_device` sigchain ops.
- `expires_at` enforcement during claim verify.
- Typed `VerificationStatus.status` reflecting the five failure modes
(`valid` / `revoked` / `expired` / `unreachable` / `fork`).
- Auth-required publishers (GitHub gist, Bluesky, ActivityPub).
## License ## License