1 files changed, 142 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..08a24ec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,142 @@
+# llsh
+
+`llsh` is a statically linked terminal LLM agent for Linux. It supports
+OpenAI-compatible APIs, Anthropic, Ollama, shell and file tools, session
+history, skills and memories from `.agents/`, and optional MCP servers.
+
+## Build
+
+The repository includes source archives for curl, OpenSSL, zlib, cJSON, and
+nlohmann/json. The host GCC toolchain builds their static archives. On x86_64
+Fedora, install GNU Make, GCC/G++, Perl, `rpm`, `dnf`, `rpm2cpio`, and `cpio`,
+and allow access to Fedora repositories. The build downloads matching
+`glibc-static` and `libstdc++-static` RPMs into the ignored build directory;
+it does not install packages system-wide. Then run:
+
+```sh
+make
+```
+
+The default build creates a statically linked `./llsh` executable. To build
+and run the test suite:
+
+```sh
+make test
+```
+
+Optional checks are `make asan` (requires Clang) and `make valgrind` (requires
+Valgrind). If static glibc/libstdc++ packages are unavailable, run tests with
+the host shared runtimes:
+
+```sh
+make STATIC=0 test
+```
+
+`make clean` removes application/test outputs; `make vendor-clean` removes
+generated third-party archives so they can be rebuilt from the bundled
+sources.
+
+## Configure a model
+
+The simplest invocation supplies a provider and its credentials:
+
+```sh
+./llsh --provider openai --api-key "$OPENAI_API_KEY" "Explain this project"
+```
+
+The CLI supports `openai`, `anthropic`, and `ollama`. OpenAI-compatible
+endpoints can be selected with `--base-url`; Ollama defaults to
+`http://localhost:11434` and does not require an API key.
+
+For repeat use, configure `.agents/models.json` with a default preset:
+
+```json
+{
+  "default": "work",
+  "presets": {
+    "work": {
+      "provider": "openai",
+      "model": "gpt-5.2",
+      "api_key": "replace-with-a-key"
+    }
+  }
+}
+```
+
+Keep credentials out of committed project files. CLI options override preset
+values. See `./llsh --help` for the complete list of options.
+
+When started without a prompt in a terminal, `llsh` opens an interactive REPL.
+With a prompt argument, it runs one turn and exits:
+
+```sh
+./llsh "Summarize the files in this directory"
+```
+
+The interactive commands include `/help`, `/model`, `/agent`, `/save`,
+`/export`, `/compact`, and `/exit`. The shell can be entered with Backtab.
+
+## Tools and workspace configuration
+
+The built-in tools are `read_file`, `write_file`, `run_shell`, `use_skill`,
+`search_memories`, `embed`, `llm`, and `compact`. File and shell operations
+use the process working directory; `-C, --cwd` selects it.
+
+Model presets in `.agents/models.json` configure model connections and model
+limits; they do not configure shell policy. Put llsh runtime tool settings in
+`.agents/speakmcp-settings.json` instead:
+
+```json
+{
+  "shell_allowlist": ["git", "rg", "cat"],
+  "shell_denylist": ["git push", "rm"],
+  "confirm_destructive": true,
+  "shell_timeout_secs": 45,
+  "max_output_chars": 9000,
+  "max_file_bytes": 700000
+}
+```
+
+The global `~/.agents/speakmcp-settings.json` values are shallow-merged with
+workspace settings; workspace keys override global keys. Explicit CLI shell
+policy and limit flags override settings.
+
+llsh is not a sandbox: tool calls run with the current user's permissions,
+and absolute file paths are accepted. Shell command allow/deny policies can
+be supplied with repeatable CLI options. Destructive-command confirmation is
+available in the interactive REPL:
+
+```sh
+./llsh --shell-allow git --shell-allow rg --shell-deny git\ push \
+  --confirm-destructive "Inspect the repository"
+```
+
+The destructive-command detector is heuristic; use an operating-system
+sandbox when commands must be restricted to a security boundary.
+
+Workspace and global agent configuration can be loaded from `.agents/` and
+`~/.agents/`. Supported content includes `agents.md`, `system-prompt.md`,
+`models.json`, MCP server configuration, skills, sub-agent profiles, tasks,
+and memories. MCP server commands are not started unless explicitly trusted:
+
+```sh
+./llsh --allow-mcp "Use the configured project tools"
+```
+
+MCP tools are exposed with qualified names of the form
+`mcp__<server-name-length>_<server-name>__<tool-name>`. Use that name in a
+sub-agent's tool allowlist.
+
+## Platform and release scope
+
+The build targets x86_64 Linux and uses the host glibc ABI. Although linked
+statically, glibc's name-service lookups can load NSS shared libraries at
+runtime; use the matching glibc runtime on the target system. HTTPS requests
+also require a usable system CA certificate bundle. Other platforms and
+architectures are not currently supported by the build.
+Third-party components and their license families are listed in
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+
+## License
+
+The llsh project is licensed under the MIT License; see [`LICENSE`](LICENSE).