sunbeamdotpt · siennathesane · Jul 28, 2026
diff --git a/README.md b/README.md
@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/everruns/bashkit/actions/workflows/ci.yml/badge.svg)](https://github.com/everruns/bashkit/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Matrix](https://img.shields.io/badge/chat-%23hello%3Asunbeam.pt-0dbd8b?logo=matrix)](https://matrix.to/#/#hello:sunbeam.pt)
 [![Crates.io](https://img.shields.io/crates/v/bashkit.svg)](https://crates.io/crates/bashkit)
 [![docs.rs](https://img.shields.io/docsrs/bashkit)](https://docs.rs/bashkit)
 [![Repo: Agent Friendly](https://img.shields.io/badge/Repo-Agent%20Friendly-blue)](AGENTS.md)

diff --git a/docs/builtin_typescript.md b/docs/builtin_typescript.md
@@ -1,3 +1,9 @@
+---
+title: TypeScript in Bashkit
+description: Bashkit's embedded TypeScript interpreter (ZapCode) runs in-memory alongside bash with zero V8 dependency.
+updated_at: "2026-07-28"
+---
+
 # TypeScript in Bashkit
 
 Bashkit includes an embedded TypeScript interpreter powered by

diff --git a/docs/cli.md b/docs/cli.md
@@ -1,3 +1,9 @@
+---
+title: bashkit-cli
+description: Command-line interface for running bash scripts in a sandboxed virtual filesystem — one binary, three modes.
+updated_at: "2026-07-28"
+---
+
 # bashkit-cli
 
 Command-line interface for running bash scripts in a sandboxed virtual

diff --git a/docs/custom_builtins_js.md b/docs/custom_builtins_js.md
@@ -1,3 +1,9 @@
+---
+title: Custom Builtins in Bashkit
+description: Register your own commands as bash builtins that share the interpreter's VFS and shell state.
+updated_at: "2026-07-28"
+---
+
 # Custom Builtins in Bashkit
 
 Register your own commands as bash builtins. They behave like baked-in

diff --git a/docs/embedding.md b/docs/embedding.md
@@ -1,3 +1,9 @@
+---
+title: Embedding Bashkit
+description: Run Bashkit as a library inside your own application or agent runtime — every command reimplemented in Rust, in-process, against a virtual filesystem.
+updated_at: "2026-07-28"
+---
+
 # Embedding Bashkit
 
 Run Bashkit as a library inside your own application or agent runtime. Every
@@ -33,7 +39,7 @@ cargo add bashkit --features scripted_tool
 `http_client` enables `curl`/`wget` and the network allowlist shown below.
 Embedded Python (Monty) is a git-only dependency, so there is no `python`
 feature from the crates.io release — to run Python inside the shell see the
-[Python builtin](python.md) guide. The `pip install bashkit` wheel below is a
+[Python builtin](../crates/bashkit/docs/python.md) guide. The `pip install bashkit` wheel below is a
 separate, standalone binding.
 
 ### Minimal execution
@@ -145,7 +151,7 @@ console.log(bash.executeSync("echo $X").stdout);
 
 ## Next steps
 
-- [Custom builtins](custom_builtins.md) — add your own Rust commands to the shell.
+- [Custom builtins](../crates/bashkit/docs/custom_builtins.md) — add your own Rust commands to the shell.
 - [Snapshotting](snapshotting.md) — serialize and restore interpreter state for
   checkpoint/resume flows.
 - [Security](security.md) — sandbox boundaries and what scripts cannot do.

diff --git a/docs/filesystem.md b/docs/filesystem.md
@@ -1,3 +1,9 @@
+---
+title: Virtual filesystem
+description: Every Bashkit script runs against an in-memory virtual filesystem, not the host disk; access is granted deliberately, never by accident.
+updated_at: "2026-07-28"
+---
+
 # Virtual filesystem
 
 Every Bashkit script runs against an in-memory **virtual filesystem** (VFS), not
@@ -65,7 +71,7 @@ semantics.
 |----------------|---------|
 | **InMemoryFs** | Default (`Bash::new()`). `HashMap`-backed, thread-safe, no persistence. Seeds `/`, `/tmp`, `/home`, `/home/user`, `/dev`. |
 | **OverlayFs** | Copy-on-write over another filesystem, with whiteout tracking for deletes. |
-| **MountableFs** | Mount multiple filesystems at different paths (longest-prefix match). Always the outermost layer, enabling [live mounts](live-mounts.md). |
+| **MountableFs** | Mount multiple filesystems at different paths (longest-prefix match). Always the outermost layer, enabling [live mounts](../crates/bashkit/docs/live_mounts.md). |
 | **ReadOnlyFs** | Delegates reads, denies every mutation with `PermissionDenied` — even writes to `/tmp`, `cp`, `mv`, `rm`, `chmod`. For inspection-only sessions. |
 | **RealFs** (`realfs` feature) | Direct access to a host directory. Read-only (safe) or read-write (dangerous); path traversal blocked by canonicalisation + root-prefix checks. |
 
@@ -116,6 +122,6 @@ readonly_filesystem: bool                       # deny all VFS mutations after s
 ## See also
 
 - [Security](security.md) — the boundaries built on top of the VFS.
-- [Live mounts](live-mounts.md) — attach and detach filesystems at runtime.
+- [Live mounts](../crates/bashkit/docs/live_mounts.md) — attach and detach filesystems at runtime.
 - [Snapshotting](snapshotting.md) — serialise and restore VFS + shell state.
 - Spec: [`specs/vfs.md`](https://github.com/everruns/bashkit/blob/main/specs/vfs.md).
diff --git a/docs/git.md b/docs/git.md
@@ -1,3 +1,9 @@
+---
+title: Git
+description: Sandboxed git builtin behind the git feature flag, operating entirely on the in-memory virtual filesystem.
+updated_at: "2026-07-28"
+---
+
 # Git
 
 Bashkit ships a sandboxed `git` builtin behind the `git` feature flag. Every

diff --git a/docs/llm-tools.md b/docs/llm-tools.md
@@ -1,3 +1,9 @@
+---
+title: Bashkit as an LLM Tool
+description: BashTool wraps the Bashkit sandbox as a ready-made tool for agent frameworks, with discovery metadata, a system prompt, and streaming output.
+updated_at: "2026-07-28"
+---
+
 # Bashkit as an LLM Tool
 
 `BashTool` wraps the Bashkit sandbox as a ready-made tool for agent frameworks.
@@ -107,7 +113,7 @@ npx skills add everruns/bashkit
 
 ## Next steps
 
-- [Hooks](hooks.md) — observe, rewrite, or cancel tool calls and HTTP requests.
+- [Hooks](../crates/bashkit/docs/hooks.md) — observe, rewrite, or cancel tool calls and HTTP requests.
 - [Security](security.md) — the sandbox boundaries every tool call runs inside.
 - Examples: [agent and tool flows](https://github.com/everruns/bashkit/tree/main/examples).
 - Full API reference: [docs.rs/bashkit](https://docs.rs/bashkit/latest/bashkit/).
diff --git a/docs/networking.md b/docs/networking.md
@@ -1,3 +1,9 @@
+---
+title: Networking & HTTP
+description: Bashkit's curl, wget, and http builtins are default-deny; you opt in host by host with a NetworkAllowlist.
+updated_at: "2026-07-28"
+---
+
 # Networking & HTTP
 
 Bashkit's HTTP builtins — `curl`, `wget`, and `http` — are the only way a script
@@ -107,13 +113,13 @@ exposes the coarse `--http-allow-all` switch for trusted use.
 
 ## Observing and rewriting requests
 
-HTTP requests flow through the same [hooks](hooks.md) pipeline as the rest of the
+HTTP requests flow through the same [hooks](../crates/bashkit/docs/hooks.md) pipeline as the rest of the
 interpreter, so a host can observe, rewrite, or cancel an outbound request before
 it leaves — useful for logging, header injection, or policy enforcement.
 
 ## See also
 
-- [Credential injection](credential-injection.md) — attach secrets to outbound
+- [Credential injection](../crates/bashkit/docs/credential-injection.md) — attach secrets to outbound
   requests without exposing them to the script.
 - [Request signing](request-signing.md) — cryptographic bot identity for signed
   outbound requests.

diff --git a/docs/request-signing.md b/docs/request-signing.md
@@ -1,3 +1,9 @@
+---
+title: Request signing
+description: Bashkit transparently signs every outbound HTTP request with an Ed25519 signature per RFC 9421, replacing spoofable identity with verifiable bot identity.
+updated_at: "2026-07-28"
+---
+
 # Request signing
 
 Bot identity on the web has historically been an honor system. A `User-Agent`
@@ -115,7 +121,7 @@ The nonce defends against replay; the expiry window bounds signature validity.
 ## See also
 
 - [Networking & HTTP](networking.md) — the allowlist that gates every request.
-- [Credential injection](credential-injection.md) — attach bearer tokens without
+- [Credential injection](../crates/bashkit/docs/credential-injection.md) — attach bearer tokens without
   exposing them to scripts.
 - Spec: [`specs/request-signing.md`](https://github.com/everruns/bashkit/blob/main/specs/request-signing.md).
 - [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421) ·

diff --git a/docs/scripted-tools.md b/docs/scripted-tools.md
@@ -1,3 +1,9 @@
+---
+title: Scripted tool orchestration
+description: ScriptedTool collapses multi-step LLM tool calls into a single bash script that composes tools, pipes, loops, and branches in one call.
+updated_at: "2026-07-28"
+---
+
 # Scripted tool orchestration
 
 Give an LLM ten tools and a ten-step task, and you pay for ten round-trips —

diff --git a/docs/security.md b/docs/security.md
@@ -1,3 +1,9 @@
+---
+title: Security in Bashkit
+description: High-level overview of Bashkit's sandbox security model — every design decision considers what an untrusted script could do and how to prevent it.
+updated_at: "2026-07-28"
+---
+
 # Security in Bashkit
 
 Bashkit is a virtual Bash interpreter designed for safe, sandboxed script

diff --git a/docs/snapshotting.md b/docs/snapshotting.md
@@ -1,3 +1,9 @@
+---
+title: Snapshotting in Bashkit
+description: Serialize an interpreter into opaque bytes and restore it later — for checkpoint/resume flows, warm sandbox caching, or rollbacks.
+updated_at: "2026-07-28"
+---
+
 # Snapshotting in Bashkit
 
 Bashkit can serialize an interpreter into opaque bytes and restore it later.

diff --git a/docs/structured-data.md b/docs/structured-data.md
@@ -1,3 +1,9 @@
+---
+title: Structured data
+description: Beyond jq, Bashkit ships small builtins for CSV, JSON, YAML, and TOML that read from a file argument or stdin and pipe naturally.
+updated_at: "2026-07-28"
+---
+
 # Structured data
 
 Beyond `jq`, Bashkit ships small builtins for the formats scripts hit most often:
@@ -7,7 +13,7 @@ file argument or from stdin so they pipe naturally.
 
 | Builtin | Format | Reach for it when |
 |---------|--------|-------------------|
-| [`jq`](jq.md) | JSON | You need real JSON transformation — filters, construction, reduction. |
+| [`jq`](../crates/bashkit/docs/jq.md) | JSON | You need real JSON transformation — filters, construction, reduction. |
 | `json` | JSON | You want a quick `get` / `set` / `keys` / `length` without jq syntax. |
 | `csv` | CSV | Selecting columns, filtering rows, counting, sorting tabular data. |
 | `yaml` | YAML | Reading a value out of a config file by dotted path. |
@@ -76,7 +82,7 @@ echo "starting on $port"
 
 ## See also
 
-- [jq builtin](jq.md) — the full JSON query engine, with its own compatibility
+- [jq builtin](../crates/bashkit/docs/jq.md) — the full JSON query engine, with its own compatibility
   reference.
-- [Compatibility](compatibility.md) — the complete builtin coverage matrix.
+- [Compatibility](../crates/bashkit/docs/compatibility.md) — the complete builtin coverage matrix.
 - [Browse all builtins](/builtins) — every registered command.