Populate template assets

2026-05-22 17:07:12 -06:00
parent f2535bb71e
commit 2eaa2098e5
7 changed files with 227 additions and 1 deletions
@@ -1,2 +1,143 @@
 # loki-config-template
-Starter template for Loki configurations. Fork it, customize the agents/roles/macros/tools/MCP servers, then `loki --install-from &lt;your-fork>`
+
+A starter template for sharing [Loki](https://github.com/Dark-Alex-17/loki)
+configurations — agents, roles, macros, tools, and MCP servers — via any
+git repository.
+
+Fork this repo, customize the assets to your taste, then install your fork
+into Loki with a single command.
+
+## Quick start
+
+Install everything in this template into your local Loki config:
+
+```sh
+loki --install-from https://github.com/<you>/loki-config-template
+```
+
+…or from within the Loki REPL:
+
+```
+.install remote https://github.com/<you>/loki-config-template
+```
+
+Pin to a specific branch, tag, or commit by suffixing `#<ref>`:
+
+```sh
+loki --install-from https://github.com/<you>/loki-config-template#v1.0.0
+loki --install-from https://github.com/<you>/loki-config-template#main
+loki --install-from https://github.com/<you>/loki-config-template#abc1234
+```
+
+Restrict the install to a single asset category with `--filter`:
+
+```sh
+loki --install-from https://github.com/<you>/loki-config-template --filter agents
+loki --install-from https://github.com/<you>/loki-config-template --filter mcp_config
+```
+
+Valid filter values: `agents`, `roles`, `macros`, `functions`, `mcp_config`.
+
+Skip per-file conflict prompts with `--install-force`:
+
+```sh
+loki --install-from https://github.com/<you>/loki-config-template --install-force
+```
+
+## Layout
+
+Loki only reads these top-level directories. Anything else in the repo is
+ignored.
+
+```
+loki-config-template/
+├── agents/
+│   └── <agent-name>/
+│       ├── config.yaml            # LLM-loop agent
+│       │   └── (or graph.yaml)    # Graph agent
+│       ├── README.md              # Optional
+│       ├── tools.sh               # Optional agent-local tools
+│       └── scripts/               # Optional graph-node scripts
+├── roles/
+│   └── <role-name>.md             # Role with frontmatter + prompt body
+├── macros/
+│   └── <macro-name>.yaml          # Positional/rest-args + REPL command steps
+└── functions/
+    ├── tools/
+    │   └── *.sh / *.py / *.ts     # Global tools (auto chmod +x on install)
+    └── mcp.json                   # MCP server config (merged with local)
+```
+
+The `functions/mcp.json` file is **merged** into your existing local file
+on install (not overwritten). For conflicting server names, you'll be
+prompted to keep yours, take the remote's, or rename the remote entry.
+
+## What's in this template
+
+| Asset | File | What it is |
+|---|---|---|
+| Agent  | `agents/hello-agent/config.yaml`  | Tiny LLM-loop agent that greets the user. |
+| Role   | `roles/explainer.md`              | Role that explains technical concepts simply. |
+| Macro  | `macros/greet.yaml`               | Macro showing positional and rest-arg variables. |
+| Tool   | `functions/tools/greet.sh`        | Bash tool using Loki's argc-style annotations. |
+| MCP    | `functions/mcp.json`              | One vanilla server + one with a vault secret reference. |
+
+Each sample is intentionally minimal. Replace it with your own work, or
+delete what you don't need.
+
+## Customizing
+
+### Agents
+Each agent lives in its own subdirectory under `agents/`. For LLM-loop
+agents, put a `config.yaml` (full schema:
+[Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Agents)). For
+declarative graph agents, put a `graph.yaml` instead
+([Graph Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents)).
+
+### Roles
+Each `roles/<name>.md` is a YAML frontmatter block followed by the role
+instructions ([Roles wiki](https://github.com/Dark-Alex-17/loki/wiki/Roles)).
+
+### Macros
+Each `macros/<name>.yaml` is a list of REPL commands to execute, with
+optional positional/rest variables
+([Macros wiki](https://github.com/Dark-Alex-17/loki/wiki/Macros)).
+
+### Tools
+Tools in `functions/tools/` follow Loki's argc-style schema
+([Custom Tools wiki](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools)).
+Bash, Python, and TypeScript scripts are auto-detected and given the
+executable bit on install.
+
+### MCP servers
+Add or modify entries in `functions/mcp.json`
+([MCP Servers wiki](https://github.com/Dark-Alex-17/loki/wiki/MCP-Servers)).
+Use `{{SECRET_NAME}}` placeholders for values you don't want to commit;
+Loki will detect missing secrets after the merge and prompt you to add
+them to the vault (or list them for you to add via `loki --add-secret`).
+
+## Secrets workflow
+
+Anywhere you reference a secret in `mcp.json` (or in any installed file),
+use the `{{NAME}}` placeholder syntax. After `--install-from` completes:
+
+- **Interactive mode**: Loki prompts you per-secret to add the value to
+  the vault. On the first "Yes," it creates the vault password file if
+  needed.
+- **Non-interactive mode** (CI, piped): Loki prints a final reminder
+  listing every missing secret with the `loki --add-secret <NAME>` /
+  `.vault add <NAME>` commands you can run to fill them in.
+
+See the [Vault wiki](https://github.com/Dark-Alex-17/loki/wiki/Vault) for
+the full secrets workflow.
+
+## Tips for forks
+
+- Pin your fork to tagged releases so consumers can install with
+  `#<tag>` for reproducibility.
+- Keep agent-local logic in `agents/<name>/scripts/` and tools.sh — global
+  tools (in `functions/tools/`) are shared across every agent.
+- The `mcp.json` merge is *additive*. If you remove a server from your
+  fork, existing installs of that server are NOT pruned. That's by design.
+- Use `--filter` to ship just one category if your repo is mixed (e.g., a
+  repo of just MCP servers can be consumed with `--filter mcp_config`).