# lore

The shared knowledge base for the homelab. Two parts:

1. **`lore.wiki.git`** — the wiki itself. The cross-project, append-only
   source of truth for decisions, pitfalls, patterns, entities, and
   project state. Catalog: <https://git.homelab.local/kaykayyali/lore/wiki>

2. **`lore.git`** (this repo) — the agent skill that interfaces with
   the wiki. Install once per agent and it knows how to read, draft,
   commit, and push wiki pages following the wiki's own protocol.

## What goes in the wiki

Anything an agent on a *different* project might need in the future.
Decisions with rationale. Pitfalls (something broke, here's why).
Patterns (something worked, capture it). New projects, services,
facets. Project state.

## What stays in local memory

Session-private notes. Working memory for the current task. Drafts
of pages before they're approved. Anything project-private.

Rule of thumb: **if another agent on a different project would
benefit, it belongs in the wiki.** Local memory is for the current
session only.

## Install the skill

Copy or symlink the `skills/lore/` directory into your agent's skills
directory.

For Claude Code:

```bash
# From this repo
ln -s "$(pwd)/skills/lore" ~/.claude/skills/lore
```

For other agents, follow their skill-loading convention. The skill
file is `skills/lore/SKILL.md` — the `name: lore` frontmatter and
the `description: ...` block tell the agent when to load it.

## Use

```bash
# Pull the latest wiki into ~/lore-wiki (clones on first run)
./skills/lore/scripts/lore-sync.sh

# Read first
less ~/lore-wiki/Schema.md
less ~/lore-wiki/Write\ Protocol.md
less ~/lore-wiki/Agent\ Onboarding.md

# Write — follow the protocol exactly
# Draft files in ~/lore-wiki/, update Index.md and Log.md,
# show the user the diff, then:
./skills/lore/scripts/lore-add.sh "<file>" [<file>...]
```

The skill's `SKILL.md` has the full workflow and rule set.

## Repo layout

```
lore.git/
├── README.md                       # this file
└── skills/
    └── lore/
        ├── SKILL.md                # the agent skill
        ├── references/
        │   └── QUICKREF.md         # condensed Schema for fast drafting
        └── scripts/
            ├── lore-sync.sh        # clone / pull --rebase
            └── lore-add.sh         # stage + commit + push
```

## See also

- Wiki: <https://git.homelab.local/kaykayyali/lore/wiki>
- Wiki git: `git@git.homelab.local:kaykayyali/lore.wiki.git`
- Wiki Home: <https://git.homelab.local/kaykayyali/lore/wiki/Home>
- Wiki Schema: <https://git.homelab.local/kaykayyali/lore/wiki/Schema>
- Wiki Write Protocol: <https://git.homelab.local/kaykayyali/lore/wiki/Write-Protocol>
- Wiki Agent Onboarding: <https://git.homelab.local/kaykayyali/lore/wiki/Agent-Onboarding>