# Lore

> Use when working in a Lore repository; installing the Lore CLI;

- **Type:** Skill
- **Install:** `agentstack add skill-abostrom-lore-skill-lore`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ABostrom](https://agentstack.voostack.com/s/abostrom)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ABostrom](https://github.com/ABostrom)
- **Source:** https://github.com/ABostrom/lore-skill/tree/master/skills/lore
- **Website:** https://lore.org

## Install

```sh
agentstack add skill-abostrom-lore-skill-lore
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# lore

Lore is Epic's open-source, content-addressed version control system for code **and** large binary assets. Every payload, tree node, and revision is keyed by its BLAKE3 hash, so a repository is a Merkle DAG: one 32-byte root hash verifies the whole tree. Workspaces are **sparse by default** and hydrate fragments on demand. Lore is exposed through a single `lore` CLI and through Python/JavaScript/C#/Go SDKs that all bind to one C ABI — the CLI is just another consumer of that API, not a privileged one.

> **Verified against Lore CLI 0.8.3+201 on 2026-06-18. SDK repos: lore-python @ 4f90b7f, lore-js @ 396ad34, lore-dotnet @ a56df73, lore-go @ 91ea1c5.**

## Iron rules

1. **Every CLI command accepts `--help`.** Run `lore  --help` before guessing flags — flags differ per subcommand and Lore is pre-1.0 (it changes between minor versions).
2. **Don't invent commands or SDK operations.** If a verb isn't in the Quick Reference below (or `reference/cli.md`), or an op isn't in `reference/sdk/model.md`, look it up. **CLI verb names are NOT the same as SDK operation names** — never assume `lore commit` maps to a method called `commit` (it's `revision_commit`).
3. **Know whether you're offline or online before acting.** The `--offline` global flag (CLI) / `offline=True` global arg (SDK) is load-bearing. Local-only work (create, stage, commit, branch, diff against cached data) needs no network; push/clone/sync against a remote do. Offline mode never makes network round-trips and never lazy-fetches.
4. **SDK calls bracket their lifecycle:** `log_configure` first, `shutdown` last. Every operation is `Lore.(globals, args).callback(handler).wait()`. Skipping `shutdown` leaks the native runtime.

## Detection gate

Before doing anything, confirm the environment. If a precondition is missing, **stop and tell the user** — never silently fall back to git or Perforce.

- **CLI work:** is `lore` on `PATH`? (`lore --version` → expect `lore 0.8.3+...`). If not, it's not installed → `reference/setup.md`.
- **In a repo?** Is the cwd (or `--repository `) a Lore repo? A repo has a `.lore/` directory. `lore status` confirms it. If not, the user needs `lore repository create` / `lore clone` first.
- **SDK work:** is the language binding installed (e.g. `pip install lore-vcs` for Python)? The native lib must be reachable — building the Python types from source needs `LORE_BUILD_PATH` set to the liblore install. If the binding/lib is absent → stop and tell the user; do not hand-roll FFI.

## Invocation & exit behavior

**CLI.** `lore [GLOBAL OPTIONS]  [ARGS]`. The repository is the cwd unless you pass the global `--repository `. Globals (`--offline`, `--remote`, `--local`, `--identity`, `--log-level`, `--dry-run`, `-f/--force`, `--no-pager`, `--non-interactive`) go **before** the subcommand. Note real shapes that differ from git/p4:

- `lore repository create  --repository  --offline` — the URL is positional (e.g. `lore://local/name` for an offline local repo).
- `lore stage ` — directory paths stage only files already marked dirty; pass `--scan` to walk the filesystem, or mark first with `lore dirty`.
- `lore commit '' --identity ` — the **message is a positional argument, not `-m`**. A fresh install has no default identity, so `--identity` is required unless set in `.lore/config.toml`.

Exit `0` = success, non-zero = failure (commit without identity exits `1`, etc.). Report the verbatim error and stop.

**SDK lifecycle** (Python shown; other languages share the model — see `reference/sdk/model.md`):

```python
from lore import Lore
from lore.types import LoreLogConfig
from lore.types.args import LoreGlobalArgs, LoreRepositoryCreateArgs
from lore.types.enums import LoreEventTag

Lore.log_configure(LoreLogConfig(file=True, file_path=LOG))   # 1. first
Lore.global_callback(LoreEventTag.LOG, logger)                # optional: process-wide handler
g = LoreGlobalArgs(repository_path=PATH, offline=True)        # globals (offline!)
a = LoreRepositoryCreateArgs(repository_url="lore://local/x") # op-specific args
result = Lore.repository_create(g, a).callback(handler).wait()# operation: globals, args
# ... file_stage, revision_commit, (branch_push / repository_clone online) ...
Lore.shutdown()                                               # last
```

## Goal-directed planning

When the user states a goal, work **backwards** to a precondition that already holds, then execute forward verifying each step:

1. **Commit** (`lore commit '' --identity `) requires →
2. **staged files** (`lore stage `; check with `lore status`) requires →
3. **a repository** (`lore repository create ` or `lore clone `) requires →
4. **the CLI installed** (`lore --version`).

Online goals add: push (`lore push`) requires a remote + authentication (`lore login `). Verify each precondition (`lore status`, `lore --version`, `.lore/` exists) rather than assuming; if one is unreachable, stop and report.

## Quick reference — CLI

CLI verbs only (captured live from `lore --help`; full flag detail in `reference/cli.md`). Globals like `--repository`, `--offline`, `--identity` apply to all.

| Want to… | Command |
|---|---|
| Check the CLI version | `lore --version` |
| Create a local (offline) repo | `lore repository create  --repository  --offline` |
| Clone a remote repo | `lore clone  [path]` |
| Show working-tree status | `lore status [path...]` (add `--scan` to reconcile from disk) |
| Mark files changed (no read) | `lore dirty ` |
| Stage changes | `lore stage ` (or `lore stage --scan `) |
| Stage a move/rename | `lore stage move  ` |
| Unstage / reset a path | `lore unstage ` / `lore reset ` |
| Commit staged changes | `lore commit '' --identity ` |
| Show revision history | `lore history` |
| Diff a file (vs current revision) | `lore diff ` |
| List / create / switch branches | `lore branch list` / `lore branch create ` / `lore branch switch ` |
| Push commits to remote | `lore push [branch]` |
| Sync to a repository state | `lore sync [revision]` |
| Lock a file | `lore lock acquire ` |
| Authenticate the CLI | `lore login [remote-url]` |
| Manage auth tokens/identities | `lore auth` (e.g. `lore auth list`) |
| Run / start / stop a service process | `lore service run` / `lore service start` / `lore service stop` |
| Manage links (versioned deps) | `lore link` (e.g. `lore link list`) |
| Manage layers (local overlays) | `lore layer` (e.g. `lore layer list`) |
| Manage the shared store | `lore shared-store` |
| Subscribe to notifications | `lore notification subscribe` |
| Generate shell completions | `lore completions ` |

## Quick reference — SDK

SDK operations only. These are `Lore.(globals, args)` methods — **names are NOT the CLI verbs.** Full surface in `reference/sdk/model.md`.

| Want to… | Call |
|---|---|
| Configure logging (always first) | `Lore.log_configure(LoreLogConfig(...))` |
| Register a global event handler | `Lore.global_callback(LoreEventTag.X, fn)` |
| Create a repository | `Lore.repository_create(g, LoreRepositoryCreateArgs(...))` |
| Clone a repository | `Lore.repository_clone(g, LoreRepositoryCloneArgs(...))` |
| Show status | `Lore.repository_status(g, LoreRepositoryStatusArgs(...))` |
| Stage files | `Lore.file_stage(g, LoreFileStageArgs(paths=...))` |
| Unstage files | `Lore.file_unstage(g, LoreFileUnstageArgs(...))` |
| Commit a revision | `Lore.revision_commit(g, LoreRevisionCommitArgs(message=...))` |
| Revision history | `Lore.revision_history(g, LoreRevisionHistoryArgs(...))` |
| Create / switch a branch | `Lore.branch_create(...)` / `Lore.branch_switch(...)` |
| Push a branch | `Lore.branch_push(g, LoreBranchPushArgs(...))` |
| Sync a revision | `Lore.revision_sync(g, LoreRevisionSyncArgs(...))` |
| Acquire a file lock | `Lore.lock_file_acquire(g, LoreLockFileAcquireArgs(...))` |
| Log in interactively / with token | `Lore.auth_login_interactive(...)` / `Lore.auth_login_with_token(...)` |
| Start / stop a service | `Lore.service_start(...)` / `Lore.service_stop(...)` |
| Tear down (always last) | `Lore.shutdown()` |

## Concept clarifications

- **Offline vs online mode.** Offline (CLI `--offline`, SDK `offline=True`) works entirely against the local mutable + immutable store: create, stage, commit, branch, diff, switch — no round-trips, no lazy fetch (it declines rather than reaching the network). Online (`--remote`, a real remote URL, or default when a remote is configured) is needed for `clone`, `push`, `sync`, and on-demand hydration. Push converges local and remote via compare-and-swap: it succeeds atomically only if the remote still matches what the client expected.
- **Global args vs op args.** Every SDK operation takes two argument objects: `LoreGlobalArgs` (repository path, `offline`, connection limits — the same things the CLI's pre-command global flags set) and a per-operation `LoreArgs` (e.g. `LoreFileStageArgs(paths=...)`). Don't put op-specific fields on globals or vice-versa.
- **Callback / event model.** Operations are asynchronous and stream typed events. You attach a handler with `.callback(fn)` (per-op) or `Lore.global_callback(tag, fn)` (process-wide), then `.wait()` for completion. Events are tagged by `LoreEventTag` (`PROGRESS`, `ERROR`, `COMPLETE`, `LOG`, `END`, plus hundreds of operation-specific tags); read payloads off the event object. Log verbosity is `LoreLogLevel` (`NONE`…`ERROR`).

## Load reference when…

- Learning Lore — architecture, content-addressing/Merkle DAG, offline/online, hydration & sparse workspaces (`.lore/view`, `.loreignore`), links vs layers, glossary → `reference/concepts.md`
- Installing the CLI, initializing/cloning, local-vs-server setup, auth, building from source → `reference/setup.md`
- Full CLI command + flag detail for daily VCS work → `reference/cli.md`
- A CLI or SDK command failed or behaves oddly → `reference/troubleshooting.md`
- The universal SDK model — globals/op-args, the `op(globals, args).callback().wait()` lifecycle, the event/callback system, logging, shutdown → `reference/sdk/model.md`
- A language-specific SDK quickstart + worked example → `reference/sdk/python.md`, `reference/sdk/javascript.md`, `reference/sdk/dotnet.md`, `reference/sdk/go.md`

## Anti-patterns

- **Don't assume git/Perforce syntax.** No `-m` for commit messages (positional), no `git add`/`p4 add` (it's `lore dirty` + `lore stage`, and bare directory staging needs `--scan` or prior `lore dirty`), no `git init` (it's `lore repository create `). When unsure, run `lore  --help`.
- **Don't skip `shutdown`.** Every SDK session ends with `Lore.shutdown()` (and starts with `log_configure`), or the native runtime leaks.
- **Don't forget offline mode for local-only work.** If there's no remote (or you don't want network), pass `--offline` / `offline=True`; otherwise operations may try to reach a server and stall or fail.
- **Don't hand-roll FFI** (`lore.native` / the raw C ABI) when the fluent `Lore.(...).callback().wait()` API covers the task. Drop to native only for operations the high-level API genuinely doesn't expose.
- **Don't invent CLI verbs or SDK ops.** If it isn't in the Quick Reference, `reference/cli.md`, or `reference/sdk/model.md`, it doesn't exist — and don't assume a CLI verb and an SDK op share a name.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ABostrom](https://github.com/ABostrom)
- **Source:** [ABostrom/lore-skill](https://github.com/ABostrom/lore-skill)
- **License:** MIT
- **Homepage:** https://lore.org

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-abostrom-lore-skill-lore
- Seller: https://agentstack.voostack.com/s/abostrom
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.