> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basemode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Where things live

> Every file base writes and the directory it goes in, which of it is specific to one machine, and which of it travels with a repository when someone else clones it.

base writes to three places: the global tier in your home directory, a workspace tier inside each registered project, and a code map beside each app. Nothing else on your machine is touched after the install.

## The global tier

`~/.base-gbl/` loads in every workspace.

| Path                      | What it holds                                                      |
| ------------------------- | ------------------------------------------------------------------ |
| `.base/graph.nq`          | The global graph.                                                  |
| `.base/changes.jsonl`     | The change log for that graph, appended on every successful write. |
| `.base/hook-events.jsonl` | What the hooks did, for debugging.                                 |
| `base.toml`               | Global configuration.                                              |
| `domains.toml`            | Global domain triggers.                                            |
| `commands.toml`           | Star commands.                                                     |
| `standards.toml`          | Standards, which fire on file edits rather than keywords.          |
| `manifest.toml`           | What is installed on this machine and at which version.            |
| `operator.toml`           | Your identity profile, if you created one.                         |
| `.env`                    | Secrets, mode `0600`.                                              |
| `handoffs/`, `forks/`     | Documents filed against the global tier.                           |

## A workspace tier

`{workspace}/.base/` is created by `base scaffold` and belongs to one project.

| Path                  | What it holds                                        |
| --------------------- | ---------------------------------------------------- |
| `graph.nq`            | That workspace's graph.                              |
| `changes.jsonl`       | Its change log.                                      |
| `hook-events.jsonl`   | Its hook activity.                                   |
| `domains.toml`        | Domain triggers that overlay the global set by name. |
| `handoffs/`, `forks/` | Documents filed against this workspace.              |

Configuration files here overlay their global counterparts by name rather than replacing them, so a workspace only needs to state what differs.

## The code map

`<app>/.base-ast/ast.ttl`, one per app, built by `base sync --ast`.

It sits outside both tiers and is never merged into `graph.nq`. `.base-ast/` writes its own `.gitignore` so the map excludes itself from version control, which is why a colleague who clones the repository has no code map until they run the sync themselves. That takes seconds and produces paths that are correct for their machine, which is the point.

## What is portable

Some of this is worth copying to a new machine and some of it actively should not be.

**Copy freely.** The `.toml` policy files: `domains.toml`, `commands.toml`, `standards.toml`, and the parts of `base.toml` that are preference rather than machine state. These are things you wrote, they are structured text, and they are reasonable to keep in version control and reapply.

**Travels with the repository already.** A workspace tier lives inside the project, so `{workspace}/.base/` goes wherever the project goes. Its graph still reflects whatever state that copy was in when it was committed.

**Do not copy.** `.env` holds secrets. `manifest.toml` records this machine's own install and update history. `hook-events.jsonl` is local telemetry. `~/.base-gbl/.base/graph.nq` is your global graph, which is personal rather than shared. Code maps regenerate faster than they copy, and copying one carries paths that are wrong on the new machine.

## Checking any of it

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
base doctor
base config list
base ast list
```

`base doctor` reads both graphs and exits nonzero when something is wrong. `base config list` shows the merged configuration, which is faster than opening two files and working out which key won. `base ast list` shows every code map with its path and when it was last synced.

## Next

<CardGroup cols={2}>
  <Card title="Setup reference" icon="wrench" href="/reference/setup">
    The commands that create, read and repair everything on this page.
  </Card>

  <Card title="The graph" icon="share-nodes" href="/how-it-works/the-graph">
    What is inside `graph.nq`, and why it is a text file.
  </Card>
</CardGroup>