# Introduction

Lore is an open-source project management app built on Alepha.

A project is not one fixed shape. It is a container that composes four
**capabilities**, and you pick them when you create it:

- **Work** - **quests** (the roadmap and the in-flight work), **areas**, and
  optionally **epics** (bounded initiatives that hold quests and run from
  draft to completed, see [Epics](https://latest.alepha.dev/lore/docs/guides-epics.md)), **releases**
  (the named goals epics and quests ship in) and a Kanban **board**. See
  [Quests](https://latest.alepha.dev/lore/docs/guides-quests.md).
- **Knowledge** - **folios**: project memory, wiki-linked, optionally
  end-to-end encrypted, filed in a tree. See [Folios](https://latest.alepha.dev/lore/docs/guides-folios.md).
- **Apps** - the copies you deploy, the **sigils** they report with, their
  analytics, and **blights**: deduplicated crash telemetry. See
  [Telemetry](https://latest.alepha.dev/lore/docs/guides-telemetry.md) and
  [Deploying an app](https://latest.alepha.dev/lore/docs/guides-deploying.md).
- **Support** - **feedback**, inbound bug and feature triage, plus a
  first-party request form your users can reach. See
  [Feedback](https://latest.alepha.dev/lore/docs/guides-feedback.md).

Turn a capability off and its pages, its menu entries and its search results
go with it. Nothing is deleted: turn it back on and everything is where you
left it. A project can have all four or just one, and turning them all off is
allowed - what remains is the project itself, its members, its activity feed
and its reports.

```mermaid
flowchart LR
  People[People in the browser] --> Project[Lore project]
  Agents[AI agents over MCP] --> Project
  CLI[lore CLI and CI] --> Project
  Project --> Work
  Project --> Knowledge
  Project --> Apps
  Project --> Support
  Deployed[Deployed apps] -->|sigil| Apps
```

**Reports** sits outside the four: every project has it, and each of its tabs
appears when the capability behind it does. Summary compares a period with the
one before; Flow, Backlog, Planning, Support, Knowledge, Delivery and Team explain
what moved, with one filter bar across them. See
[Reports](https://latest.alepha.dev/lore/docs/guides-reports.md).

Most of those surfaces are exposed over **MCP**, which is the primary consumer: an
AI agent reads the folio index to orient itself, drives quests as work lands, and
files what it learned back as a folio. [MCP tools](https://latest.alepha.dev/lore/docs/guides-mcp.md) lists every
tool, and what has none. `project_context` answers the capability
set first, then only the sections those capabilities own - a section a project
has turned off is absent rather than empty, so an agent is never told a project
tracks something it does not.

A connected app, whether Claude over MCP or the `lore` command after
`lore login`, reaches what a project member can do and nothing more. Its access
is limited to the project surfaces (quests, folios, feedback, apps, deploys and
the rest), so an administrator who connects Claude does not hand it the admin
pages. Those stay reachable from a signed-in session. Neither kind of
connection can create or revoke API keys or change account settings. An API
key (`LORE_API_KEY`) is not narrowed this way: it carries its owner's roles,
unless it was created with a permission scope of its own.

## Apps and their instances

An **app** is a name rather than a record. What Lore stores is one **instance**
per deployed copy: the pair `(app, env)`, so `club/production` and `club/staging`
are two instances of one app and nothing else has to exist for them to be. The
environment half is a free label, not a fixed list, so `b14-production` and
`eu-staging` are as valid as `staging`, and how finely you slice your fleet is
your decision rather than the schema's.

Creating an instance mints nothing. It records that a copy of your app runs
somewhere, and each capability is unlocked on it separately, from that instance's
**Settings** tab:

- a **sigil** is the credential the deployed copy reports with. Minting one
  unlocks Analytics, Vitals, Errors and Explore for that copy alone.
- an **estate** names the machine the copy is deployed to.

⚠️ **Removing a sigil loses that instance's analytics history** - views,
vitals, unique visitors and error groups all hang off the credential. To revoke a
leaked token, rotate it instead: the app stops reporting with the old key
immediately and every row survives.

## Why it exists

Lore is built with Alepha, and it lives in one repository beside the framework and
[Bay](https://latest.alepha.dev/bay/docs/guides-introduction.md) on purpose: it builds on the framework's
source, not a published version. It is where framework changes get used before
they are recommended: a rough edge in Alepha shows up in Lore first, and the fix
ships in the same commit as the feature that exposed it.

## Status

Lore is deployed at [lore.alepha.dev](https://lore.alepha.dev) and shares its version
number with the rest of the ecosystem.

It also ships as a self-hosted image, `ghcr.io/alepha-dev/lore`, published by the
same release that publishes the framework. One command, one volume, no
configuration:

```bash
docker run -p 3000:3000 -v lore:/data ghcr.io/alepha-dev/lore
```

See [Self-Hosting](https://latest.alepha.dev/lore/docs/guides-self-hosting.md) for what happens on first boot and
what each optional variable buys.

## Where to go next

- [Getting started](https://latest.alepha.dev/lore/docs/guides-getting-started.md) - a project, the CLI and
  an agent connected, in a few minutes.
- [Quests](https://latest.alepha.dev/lore/docs/guides-quests.md), [Epics](https://latest.alepha.dev/lore/docs/guides-epics.md) and
  [Releases](https://latest.alepha.dev/lore/docs/guides-releases.md) - planning and tracking the work.
- [The project dashboard](https://latest.alepha.dev/lore/docs/guides-project-dashboard.md) - where a
  project stands, at a glance.
- [Folios](https://latest.alepha.dev/lore/docs/guides-folios.md) and
  [Attachments](https://latest.alepha.dev/lore/docs/guides-attachments.md) - the project's memory.
- [Feedback](https://latest.alepha.dev/lore/docs/guides-feedback.md) and
  [Notifications](https://latest.alepha.dev/lore/docs/guides-notifications.md) - hearing from your users and
  from Lore.
- [Agent prompts](https://latest.alepha.dev/lore/docs/guides-agent-prompts.md),
  [Automations](https://latest.alepha.dev/lore/docs/guides-automations.md) and
  [MCP tools](https://latest.alepha.dev/lore/docs/guides-mcp.md) - putting agents to work.
- [The lore CLI](https://latest.alepha.dev/lore/docs/guides-cli.md) - every command.
- [Telemetry](https://latest.alepha.dev/lore/docs/guides-telemetry.md),
  [Healthchecks](https://latest.alepha.dev/lore/docs/guides-healthchecks.md),
  [Deploying an app](https://latest.alepha.dev/lore/docs/guides-deploying.md),
  [Artifacts](https://latest.alepha.dev/lore/docs/guides-artifacts.md),
  [Stacks](https://latest.alepha.dev/lore/docs/guides-stacks.md) and
  [Estates](https://latest.alepha.dev/lore/docs/guides-estates.md) - running your apps.
- [Self-Hosting](https://latest.alepha.dev/lore/docs/guides-self-hosting.md) - your own instance.