Alias
An operator never names a path. It names an alias, and alias/alias.json is the one place an alias
resolves to a location. alias/INDEX.md is its readable map by zone, generated by
scripts/generate-alias-doc.mjs with --check inside npm test.
An operator reads only the aliases its own Refs table names; this page is the whole vocabulary those tables draw from. Resolution takes the longest registered prefix, a sub-path narrows an alias, and a segment in angle brackets is supplied by the invocation.
Six zones
| Zone | What it holds |
|---|---|
| Workspaces | The working area: routed checkouts, the route declarations, ports, and machine identity |
| Grammar | The @starci/grammar package as the bound app resolves it — the only fact about what a component owns |
| Knowledge | Canonical law: ui, grammars, patterns. Read only |
| Worktrees | Machine-local authority and evidence outside any checkout: business heads, UAT pairs, debts, templates, the runtime owner |
| Remote | The internet: registries, git remotes, image registries, CI runs, object storage |
| Dynamic | Everything produced inside the current session and nothing that existed before it |
Binding, not just resolving
Every alias also declares how it binds, and the binding is what makes drift detectable. A checkout
binds by fingerprint plus sourceHead. @grammar binds by package version plus the resolved
location’s fingerprint. @remote/ghcr binds by digest, and the registry says why: “A tag is never a
binding; a digest is.” @remote/npm binds by version, because “latest never is.”
Writers
Each alias names who may write it. Only frontend.source.apply writes @workspaces/fe, only
backend.source.apply writes @workspaces/be, only business.decide writes
@worktrees/businesses, only uat.verify writes @worktrees/uat. This is the same fact the
workflow rule leans on when it forbids two branches of one step from sharing a write alias.
Friendly segments
Inside any checkout alias, a friendly word stands in for an exact path: husky for .husky/,
package for package.json, gates for the scripts plus the configs they name, grammar for
packages/grammar. Two more are about time rather than place: /branch/session is the session
branch — “the only branch a source-writing operator may commit to” — and /commit/<sha> names a
checkout at one commit, which is how a later step points at exactly what an earlier step wrote.
Dynamic is never an alias path
Files produced inside a session are passed as kinds, by explicit path in request.json, never as
aliases. The session folder is created by the orchestrator and deleted when git.publish finishes; a
blocked run keeps it for the resume.
The full registry, with every alias, its params, its resolution, its binding and its writers, is at Reference → Alias.