Metadata-Version: 2.5
Name: eyrie
Version: 0.3.2
Summary: A commanding place above your work — scaffold for planning across sources
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Description-Content-Type: text/markdown

# Eyrie

A commanding place above your work — scaffold for planning across sources.

Eyrie creates coordination repos where you (and your agents) can see across
multiple projects, notes, and sources without reaching down to change them.
Read-only `links/` point to the real sources; curated `docs/` build persistent
understanding over time.

## Install

```sh
uvx eyrie init my-workspace
```

Or install permanently:

```sh
uv tool install eyrie
```

## Usage

### Create a new eyrie

```sh
eyrie init my-workspace
```

You'll be asked for a one-sentence description. Eyrie then generates the full
scaffold: `AGENTS.md`, `docs/`, `links/`, git repo with a pre-commit hook, and
agent permission rules for OpenCode and Claude Code.

### Add sources

```sh
eyrie add ~/Projects/resume-cv
eyrie add ~/Documents/ObsidianVaults/Career
```

Type is inferred (`repo` if `.git/` exists, else `source`), name defaults to the
directory basename, and paths under `$HOME` are stored as `~/...` in `eyrie.toml`.
Each `add` auto-syncs (creates symlinks and appends doc skeletons).

You can also edit `eyrie.toml` directly:

```toml
[[sources]]
name = "resume"
path = "~/Projects/resume-cv"
type = "repo"

[[sources]]
name = "career-vault"
path = "~/Documents/ObsidianVaults/Career"
type = "source"
```

Every source has a `path`, pointing at either a directory or a single file. Sources
are content on disk that gets mounted read-only into `links/`.

### External systems and skills

Eyrie does not install anything. Systems you reach live rather than mount — a
`gcloud` or Todoist CLI, Jira, Confluence — are set up by you or your agent and
documented in `docs/domain/access.md`:

```sh
brew install --cask gcloud-cli
npx skills add https://github.com/onnokh/atlassian-cli --yes
```

Skills land in `.agents/skills/`, which every supported agent reads (Claude Code
via the generated `.claude/skills` symlink). Record what each one is for, and how
to authenticate, in `docs/domain/access.md` — never the credentials themselves.

### Sync

```sh
eyrie sync
```

This materializes symlinks under `links/` and appends skeleton entries to
`docs/domain/repos.md` and `sources.md`.

## How it works

```
my-workspace/
├── AGENTS.md        ← agent instructions (generated once, then yours)
├── CLAUDE.md        ← points to AGENTS.md
├── eyrie.toml       ← sources config
├── docs/            ← persistent knowledge (domain, topics, workflow)
├── links/           ← READ-ONLY symlinks to sources (git-ignored)
├── output/          ← versioned deliverables
├── scripts/         ← automation (uv run scripts/foo.py)
└── scratch/         ← ephemeral work (git-ignored)
```

The core pattern: **plan here, execute there.** Use the eyrie to understand
cross-source work, then make changes in the individual source repos.

## Updating

Upgrade the CLI:

```sh
uv tool upgrade eyrie   # if installed with `uv tool install`
uvx eyrie@latest init   # if you run it with uvx
```

**Upgrading never modifies an existing eyrie.** Everything `eyrie init` generates —
`AGENTS.md`, the `docs/` stubs, `.gitignore` — becomes yours the moment it is written,
and no command regenerates or migrates it. That is deliberate: you edit those files, and
silently overwriting your edits would be worse than leaving them stale.

To see what a newer version scaffolds, generate a throwaway and diff it:

```sh
eyrie init /tmp/scaffold-check
diff -ru /tmp/scaffold-check/docs my-workspace/docs
```

Copy over anything you want. Nothing is required.

### Upgrading to 0.3.2

`type = "folder"` is now `type = "source"`. The old name was inaccurate: a source can be a
single file, not only a directory. Change the type on every non-repo source in
`eyrie.toml` — `eyrie sync` fails and names each entry still using the old value.

### Upgrading to 0.3.0

0.3.0 removed skill installation and the `remote` source type. In each existing eyrie:

- **Delete any `skills = [...]`** from `[eyrie]` and from `[[sources]]`. They are now
  ignored without warning — install those skills yourself with
  `npx skills add <skill> --yes`.
- **Delete any `type = "remote"` blocks.** `eyrie sync` now fails on them and names the
  offending entry. Document those systems in `docs/domain/access.md` instead.
- Optionally refresh `docs/domain/access.md` from the new template, which explains access
  routes and warns against committing credentials.

`description` keys left on a source are harmless — nothing reads them.

## Requirements

- Python >= 3.11
- [uv](https://docs.astral.sh/uv/) (for running and installing)

## License

MIT
