Reference inventory and glossary

Use this page to find the authoritative chapter for a symbol or subsystem. It also inventories the shipped binaries, 49 bundled adapter heads, important files/environment variables, and the terms shared by the language, shell, Reef, kernel, and MCP layers.

Find the right chapter🔗

Start and orient🔗

Language🔗

Shell and tools🔗

Agents and protocol🔗

Operate and contribute🔗

Binary inventory🔗

The packages are separate. See install commands.

File and directory inventory🔗

Do not assume all companion defaults agree: shoal-history/doctor use XDG data in places where shell/kernel use XDG state. The path matrix is authoritative.

Environment-variable inventory🔗

Standard/XDG🔗

Kernel and MCP🔗

Capture, adapters, and secrets🔗

Configuration overrides🔗

The configuration loader also recognizes environment overrides including:

SHOAL_EDITOR_MODE
SHOAL_EDITOR_BRACKETED_PASTE
SHOAL_COMPLETION_MENU
SHOAL_COMPLETION_FUZZY
SHOAL_COMPLETION_CASE_INSENSITIVE
SHOAL_COMPLETION_MAX_RESULTS
SHOAL_HISTORY
SHOAL_HISTORY_MAX_ENTRIES
SHOAL_HISTORY_FILE
SHOAL_HISTORY_DEDUP
SHOAL_RENDER_WIDTH
SHOAL_RENDER_COLOR
SHOAL_RENDER_PAGING
SHOAL_RENDER_PAGER
SHOAL_RENDER_ECHO
SHOAL_PROMPT
SHOAL_PROMPT_TEMPLATE
SHOAL_NERD_FONT

Use Configuration and prompt for value parsing and precedence; an inventory alone is not sufficient to configure them correctly.

Bundled adapter inventory (49 heads)🔗

An adapter head is the Shoal command name selected before subcommand parsing. Availability still depends on the external executable/platform.

Source control and development🔗

cargo  git  gh  go  jj  rg  rustup

Language runtimes and interpreters🔗

bash  deno  jq  node  python  ruby  yq

JavaScript/Python/package tools🔗

brew  bun  npm  pip  pnpm  uv  yarn

Containers, orchestration, and infrastructure🔗

docker  helm  kubectl  podman  terraform

Cloud/project services🔗

aws  gcloud

Filesystem, archive, and data🔗

curl  df  du  env  fd  findmnt  sqlite3  stat  tar  unzip  zip

Linux/system inspection🔗

ip  journalctl  lsblk  lscpu  ps  ss  systemctl  systemd-analyze  vmstat  who

Count check:

7 + 7 + 7 + 5 + 2 + 11 + 10 = 49

The adapter catalog documents each head’s class, structured subcommands/output, and caveats. A listed adapter does not mean the tool is installed or every subcommand is structured.

Adapter parser inventory🔗

json
ndjson
csv
tsv
z-records
porcelain-v2
cols
cols2
tsv-headerless
lines
kv
none

See Structured output parsers for exact behavior.

MCP inventory🔗

Tools (13)🔗

shoal_exec
shoal_plan
shoal_apply
shoal_get
shoal_journal
shoal_cancel
shoal_cap_request
shoal_pty_open
shoal_pty_send
shoal_pty_read
shoal_pty_resize
shoal_pty_close
shoal_pty_list

Stable resource roots (6)🔗

shoal://journal
shoal://jobs
shoal://session/cwd
shoal://session/env
shoal://session/reef
shoal://pty

Dynamic resources add tasks, plans, and PTYs. Transcript/content values are reached from returned refs/templates.

Static event channels (4)🔗

session.transcript
journal
approval
render

Dynamic forms are task.{id} and user.{name}. There is no currently advertised Reef channel.

Kernel method inventory🔗

session.attach  session.env  session.reef
parse           complete     explain
exec            value.get    blob.get
journal.query
task.list       task.get     task.await
task.cancel     task.suspend task.resume
plan.get        plan.list    plan.apply
cap.request
pty.open        pty.send     pty.read
pty.resize      pty.close    pty.list
events.read     events.publish
events.subscribe events.unsubscribe

journal.query and cap.request currently lack the required attachment gate; treat that as a security defect, not a pre-auth API. See Kernel method index.

Short-reference inventory🔗

Equivalent resource URIs use shoal://out/N, shoal://task/N, etc. Never persist the first four as durable business IDs.

Error-code namespaces🔗

Shoal has two distinct error namespaces:

1. kernel/MCP JSON-RPC numeric codes (-32602, -32011, etc.);
2. language error-value string codes (type_error, cmd_failed, etc.).

Do not compare a language code to an RPC number. Kernel errors and language errors document their control paths.

Glossary🔗

Adapter🔗

A TOML declaration that gives a command head typed parameters, invocation rewriting, output parser/schema, accepted statuses, class, and planning effects. It wraps an external executable; it is not the executable or an OS sandbox.

Addressable value🔗

A value stored behind a short ref/resource URI so a client can retrieve a field or slice without re-executing source.

AST🔗

Abstract syntax tree produced by Shoal parsing. Kernel attach/parse currently reports AST vocabulary version 2.

CAS🔗

Content-addressed store. Journal outputs/large bytes can be stored by BLAKE3 hash and later retrieved while retained. A hash does not imply authorization or permanence.

Channel🔗

A named event conduit. Language/wire clients may publish only user.*; kernel owns semantic channels. A channel event has per-channel sequence/timestamp/payload.

Command head🔗

The first command-shaped word used for resolution, such as git in git status. It can resolve to a lexical function/alias, builtin, Reef tool, adapter, external program, or interpreter path according to current precedence.

Command mode🔗

Parser/evaluator reading where an unbound statement-head word is a command and subsequent words are arguments. It coexists with expression mode; it is not a separate shell language.

Effect🔗

Planner description such as filesystem read/write/delete, process spawn, network connect/listen, environment/secret/session/journal/time, or opaque. Effects are analysis/policy data, not proof of native program behavior.

Elision🔗

Replacement of a large wire value with type/count/schema/preview/render-head plus URI, preserving addressability while bounding context.

Evaluator🔗

The runtime object holding lexical/session state, cwd/env, Reef resolver, ports, journal, cancellation, event bus, and command execution. The local REPL and each named kernel session own separate evaluators.

Expression mode🔗

Evaluation of names/literals/operators/calls/methods. Parenthesizing a command places it at a value boundary inside an expression.

Feed🔗

Explicit serialization of a finite value to a child process’s stdin. It is the byte-boundary bridge, not a typed pipeline operator.

Hermetic🔗

Context-specific. Reef hermetic mode removes ambient PATH tail. Leash hermetic=true requests fail-closed sandbox behavior for represented dimensions. Neither alone is a full hermetic container.

Journal🔗

SQLite/WAL structured execution record with source/AST/effects/principal/status/output descriptors and optional undo inverses. Distinct from editor line history.

Leash🔗

Principal policy/effect evaluator plus OS sandbox selection. It can allow/deny/request approval and apply filesystem confinement where supported.

Outcome🔗

External/builtin process result containing status, success, signal, semantic out, stdout/stderr, duration, PID, command, and optional source span. Statement/value position controls whether non-ok raises.

Plan🔗

Derived effects/reversibility/estimates/verdict for source before spawn. Stored plans can be approved/applied. Current short identity/approval security gaps are documented prominently.

Principal🔗

Identity attached to a kernel connection: token-supplied agent string or tokenless local uid:<euid>. Leash policy keys by principal.

PTY🔗

Pseudoterminal session for interactive programs. MCP exposes a rendered emulator screen and semantic key input, not raw ANSI history.

Reef🔗

Tool constraint/resolution/lock/provider/PATH subsystem. It selects what executable/version/hash a command should use; Leash governs what behavior is allowed.

Reference (ref)🔗

A compact handle such as out:17 or task:9. Meaning depends on kind and lifetime; it is not automatically durable, secret, collision-proof, or an authorization token.

Session🔗

A named kernel evaluator namespace sharing bindings/cwd/env/transcript/tasks/PTys/Reef state. It is currently a collaboration boundary, not principal isolation.

Statement position🔗

Top-level command/control context where a non-ok outcome normally raises cmd_failed and aborts subsequent statements.

Stream🔗

Lazy/single-consumption sequence, potentially live. Live sources have bounded/coalescing behavior; streams currently do not chunk over the kernel wire or feed a process incrementally.

Task🔗

Background evaluator/kernel execution with lifecycle/cancellation/result reference. Timeout can return ongoing work as a task rather than terminate it.

Value position🔗

Expression/capture context where a failed external outcome remains inspectable as a value.

Wire value🔗

JSON object tagged by $ that represents a Shoal value across the kernel/MCP boundary. Secrets carry only names; large values can become $:"ref".

Snapshot notes🔗

• Workspace/package version is currently 0.1.0; contracts are preview.
• Conformance corpus: 1,310 cases, 1,306 pass, 4 explicit host/harness skips as of 2026-07-16.
• Bundled adapter heads: 49.
• MCP tools: 13.
• MCP protocol initialization version: 2025-06-18.
• Kernel serialized AST version: 2.
• Supported deployment platforms: Linux/macOS preview; Windows unsupported.

For changes since this inventory was written, prefer the source registries/tests and update this page in the same change.