Sharing a knowledge base

The offline share is the hero use case. Everything else exists to make this work.

M5/M9 not landed

build and import are stubs today. The mechanics described below are spec'd in spec 10 but won't run end-to-end until M5 and M9 land.

Two share modes

Default — slim zip, recipient downloads the model

local-agents build                                  # → ./my-handbook.zip
local-agents build --out ./dist/my-handbook.zip
local-agents build --to s3://bucket/x.zip           # upload instead of writing
local-agents build --to https://upload.example      # PUT to a URL

The slim zip carries the wiki, RAG chunk index, skills, and the project metadata. Not the model. The recipient's import flow notices the model isn't cached locally and downloads it from the same llama-cpu-benchmarks manifest the sender used.

Typical size: a few MB to a few hundred MB depending on data/.

--self-contained — fat zip with the model bundled

local-agents build --self-contained --to s3://bucket/x.zip

The fat zip carries everything plus the GGUF model + ONNX embedding. The recipient never makes a network call — import unpacks the model into their ~/.config/local-agents/ cache.

Typical size: 3–5 GiB (model dominates).

Recipient flow

local-agents import https://share.example.com/my-handbook.zip
cd my-handbook
local-agents serve     # opens dashboard at localhost:8080
# or
local-agents chat      # terminal REPL

Sources import accepts

local-agents import ./my-handbook.zip            # local file
local-agents import https://share.example/x.zip  # HTTPS
local-agents import s3://bucket/x.zip            # S3 (ambient AWS_*)
local-agents import URL --to ./other-name        # rename on unpack

Offline guarantee

Once import finishes, no command makes outbound network calls — chat, serve, wiki list/show/edit, doctor (in the recipient mode without eval: configured). The plane test is non-negotiable.

The eval command is the explicit exception. It needs an API key for a big-model judge and is dev-time only. Recipients of a share zip never run eval.

What travels in the zip

	always	only if --self-contained
config.yml, schema.md, wiki-instructions.md, README.md	✓
data/ raw sources	✓
wiki/ articles	✓
skills/ SKILL.md folders	✓
manifest.json (build provenance + integrity)	✓
RAG chunk index + embedding map	✓
Model GGUF		✓
Embedding ONNX		✓

Compatibility with offline-llm-knowledge-system

The zip format is shared with sister project offline-llm-knowledge-system — the browser counterpart that lets you chat against the same bundle from a Chromium tab using WebLLM. The same zip works both ways: built by pocket-llm, consumed by either CLI or browser.

Any change to the zip format must stay compatible. See spec 10.