~/.base-gbl/ loads everywhere. A workspace tier at {workspace}/.base/ belongs to one registered project and loads only there. At query time both load into one store and you search across them together.
The split maps onto a real distinction. Global is for what is true of you wherever you work: how you like code written, how you want to be talked to. Workspace is for what is true of one project: its conventions, its decisions, its people.
How a workspace is found
base walks up from the directory you are in and takes the first ancestor containing a.base/ directory. That is the workspace, and it is the only one that loads.
So the answer to “will base show me things from a different project” is no, and the reason is path resolution rather than filtering. Project B’s graph is never opened while you are standing in project A. Nothing is loaded and then hidden.
base scaffold is what creates the .base/ directory and registers the workspace globally.
Writing outside a workspace
Outside any registered workspace, base refuses to write rather than guessing a tier:-g, and that flag routes the write to ~/.base-gbl explicitly rather than by accident.
Verified from source at 0ace1ba, the commit the shipped 0.15.2 binary was built from.
Where a write lands
A handoff, fork, decision or note goes to the workspace you are in, unless you pass-g. Since 0.16.0 that includes the folders inside ~/.base-gbl where handoff and fork docs live (~/.base-gbl/handoffs, ~/.base-gbl/forks), and ~/.base-gbl itself, when your home folder is a workspace. Before 0.16.0 a shell parked in one of those folders wrote the global tier while you were inside the workspace at ~.
Outside every workspace, a folder inside ~/.base-gbl still writes the global tier, and any other folder refuses, as above.
A moved handoff or fork keeps its dates. Registering a slug with base handoff create or base fork create in a tier that does not hold it, while another tier does, is a move: the record keeps its createdAt, resurfaceAt and lastActive (the newest copy’s, when several tiers hold it), so it does not jump to the top of session start as if it were new. Registering a slug the tier already holds re-points it to now, as before. base handoff create archives the other tier’s copy, so one copy stays open; base fork create does not, so archive that one with base fork -g archive <slug>.
The -g flag, and where it goes
Six commands carry -g / --global: rule, decision, handoff, fork, learn and changes. On the four that have subcommands it belongs on the command itself, before the verb:
base graph apply-ops takes --global in long form only. Nothing else has one, so for every other command the tier is decided by where you are standing. Check base help <command> rather than assuming.
--global resolves to one fixed location, ~/.base-gbl/.base, and is never searched for. That is worth stating because it briefly was not: on a machine that had only ever run base install, the directory did not exist yet, and the resolver walked up past it and took the workspace tier instead, so every -g command reported success against the wrong graph. Fixed at 0ace1ba, the commit the shipped 0.15.2 binary was built from, with regression tests on both tiers.The workspace tier keeps the walk, and keeps refusing when the walk finds nothing. There is no known-correct location to fall back to, so guessing one would be worse than the error.How the two tiers merge
Global loads first, then the workspace graph overlays it by name into one in-memory store. A single query spans both, and rules from both tiers can arrive in the same turn. On a conflict, the workspace wins. The configuration files follow the same pattern.base.toml, domains.toml and commands.toml each layer workspace over global by name, and a workspace base.toml inherits everything from the global one unless it overrides a key explicitly.
Reads reflect the merge. base domain list, base handoff list and base fork list all show both tiers together, with the tier each entry lives in. Writes mostly do not: they go to the tier you are standing in, or to global if you passed -g.
One project’s context reaching another
There is one path by which it happens deliberately:base project peer adds a link so a project also surfaces in another workspace.
--remove takes the link back off.
To move a project outright, base project move re-homes it into another workspace’s graph and takes its tasks, domain, decisions, rules and notes with it. It prints the plan and changes nothing until you pass --yes.
Next
Where things live
Every file each tier holds, and which of it is machine-local.
Projects reference
Every project, milestone, task, goal, reminder and entity command.