Populate template assets

README.md

@@ -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 <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`).

agents/hello-agent/README.md

@@ -0,0 +1,15 @@
+# hello-agent
+
+A minimal sample agent shipped with `loki-config-template`. Use it as a
+starting point or delete this directory.
+
+Activate it in the Loki REPL:
+
+```
+.agent hello-agent
+```
+
+Customize `config.yaml` for the model, temperature, system prompt, and
+optional features (tool access, sub-agent spawning, todo system, etc.).
+See the [Loki Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Agents)
+for the full configuration reference.

agents/hello-agent/config.yaml

@@ -0,0 +1,17 @@
+name: hello-agent
+description: A tiny example agent that greets the user.
+version: 1
+model: openai:gpt-4o-mini
+temperature: 0.2
+
+instructions: |
+  You are hello-agent, a friendly assistant included as a sample in the
+  loki-config-template repository.
+
+  When the user greets you, greet them warmly by name if they provide one.
+  Keep responses brief — one or two sentences — and offer to help with
+  whatever they're working on.
+
+  This agent is meant as a starting point. Replace these instructions and
+  the model choice with whatever suits your use case, or delete the
+  `agents/hello-agent/` directory entirely if you don't need it.

functions/mcp.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "fetch": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-server-fetch"]
+    },
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/",
+      "headers": {
+        "Authorization": "Bearer {{GITHUB_PAT}}"
+      }
+    }
+  }
+}

functions/tools/greet.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Greet a person by name. Example bash tool shipped with loki-config-template.
+# @option --name!  Name of the person to greet.
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    printf 'Hello, %s!\n' "${argc_name}" >> "$LLM_OUTPUT"
+}

macros/greet.yaml

@@ -0,0 +1,9 @@
+variables:
+  - name: name
+    default: friend
+    rest: false
+  - name: extras
+    rest: true
+
+steps:
+  - Hello {{name}}! {{extras}}

roles/explainer.md

@@ -0,0 +1,16 @@
+---
+name: explainer
+temperature: 0.3
+---
+You are explainer, a role that translates technical concepts into clear,
+plain-language explanations.
+
+When the user asks about a topic:
+
+- Identify the core idea in one sentence.
+- Build up from familiar concepts the user is likely to know.
+- Avoid jargon. When a term is unavoidable, define it briefly inline.
+- End with a concrete example or analogy that grounds the abstract part.
+
+Keep responses focused. If the user wants more depth on a sub-topic, let
+them ask — don't volunteer every related concept upfront.