# Multi-Repo Workspaces

<!-- FLY-1138: full exposition moved here from AGENTS.md, which keeps a
     condensed summary plus a pointer. Update both when the topology rules
     change. -->

In a multi-repo workspace (topology type 4), the directory structure is:

```
workspace-root/          ← .flydocs-workspace.json, .claude/, AGENTS.md
├── repo-a/              ← .flydocs/config.json, flydocs/context/
├── repo-b/              ← .flydocs/config.json, flydocs/context/
└── repo-c/              ← .flydocs/config.json, flydocs/context/
```

**Key rules:**

- **Skills and scripts live at workspace root** (`.claude/skills/`). Child
  repos do NOT have their own `.claude/skills/`. Any `.claude/` content
  inside child repos is legacy and should be ignored.
- **Config and context live in each child repo** (`.flydocs/config.json`,
  `flydocs/context/project.md`, `flydocs/context/service.json`).
- **`.flydocs-workspace.json`** at workspace root is the topology index with
  per-repo purpose, stack, and dependencies.
- **Identity is global** — `~/.flydocs/me.json` and `~/.flydocs/credentials`.

**Running operations from workspace root:** no `cd`. The runner finds the repo
that owns `.flydocs/config.json` itself — from the working directory, or from
`--repo <name>` when the workspace root implies no single repo:

```bash
flydocs run issue.list --repo repo-a --active   # from the workspace root
flydocs run issue.list --active                 # from inside repo-a
```

`--repo` takes a repo name from `.flydocs-workspace.json`, or a path. It is
reserved across every operation, so it always means the same thing.

Invoking a dispatcher script directly still requires the child repo as the
working directory — that `cd` is what the runner exists to remove.