Mount layout: add indexes, semantic aliases, and a SKILL.md to reduce agent file-shopping

[khaliqgant]

Context

While benchmarking relayfile vs MCP (GitHub + Linear + Notion) across Haiku / Sonnet / Opus, we hit a regression on Opus where relayfile cost ~20% more than MCP despite using slightly fewer end-state context tokens. Investigating the mount layout (~/relayfile-mount) confirmed the cause: the layout forces agents to scan-and-read to find anything, which racks up turns and output tokens even when final context is lean.

This is a layout problem, not an architectural one. Fixes are straightforward and should dramatically improve every cost/latency metric — especially on the most common task ("find this thing by name").

Current layout (problems)

~/relayfile-mount/
├── github/repos/AgentWorkforce/<repo>/        # 76 repos pre-materialized
│   ├── metadata.json
│   ├── issues/
│   └── pulls/
├── linear/
│   ├── issues/<uuid>.json                      # UUID-named, no index
│   ├── comments/<uuid>.json
│   ├── users/<uuid>.json
│   └── teams/<uuid>.json
└── notion/
    ├── pages/<uuid>.json                       # 530 pages, UUID-named
    └── databases/<uuid>/...

Sample Linear issue:

{"id":"d69f953e-...","identifier":"AGE-8","title":"Change all canonicals to agentrelay.com","state_name":"Done",...}

Five problems, in order of damage

1. No index files anywhere. No _index.json, no README.md, no MANIFEST. The agent's only entry point is ls, which returns UUIDs with zero semantic info.

2. UUID-named files for everything. To answer "show me Notion page 'Khaliq's To Dos'" the agent has to either grep -l across all 530 files or sample-read until it finds the right title. MCP's search_pages(query) is one tool call; relayfile here is N file reads.

3. No state-grouped views. linear/issues/ mixes Done / Todo / In Progress. "List open issues" requires reading every file and filtering by state_name. No linear/issues/by-state/Todo/.

4. GitHub mount has 76 repos pre-materialized. When the user asks about one repo, the agent still sees the full repos list. Pure noise.

5. No SKILL.md / layout doc. The agent has to discover the layout every run. Wasted turns just learning the mount.

Proposed fixes (priority-ranked by ROI)

1. Add _index.json to every directory (biggest single win)

// notion/pages/_index.json
[
  {"id":"3196800c-...","title":"Khaliq's To Dos","url":"...","updated":"2026-05-07"},
  ...
]

"Show me page X" becomes: read _index.json (1 file) → find by title → read the UUID file (2nd file). 2 reads instead of 530.

2. Semantic-key symlinks/aliases

notion/pages/by-title/Khaliq's To Dos.json  →  ../<uuid>.json
linear/issues/by-id/AGE-8.json              →  ../<uuid>.json

Direct lookup by name. 1 read.

3. State-grouped subdirs for filterable types

linear/issues/by-state/Todo/AGE-12.json
linear/issues/by-state/In Progress/AGE-15.json
linear/issues/by-state/Done/AGE-8.json

"List open issues" → ls linear/issues/by-state/Todo/. Zero file reads needed for the listing.

4. Top-level LAYOUT.md (or SKILL.md) at the mount root

Teaches the agent the structure on first look so it doesn't waste turns discovering. Claude Code agents are excellent at reading skill-style markdown; this maps directly to how they're trained.

# Mount layout
- `notion/pages/_index.json` — list of all pages with titles. Read this first.
- `notion/pages/by-title/<title>.json` — direct lookup by title.
- `linear/issues/by-state/<state>/` — grouped by state.
- `linear/issues/by-id/<identifier>.json` — direct lookup, e.g. AGE-8.

5. Lazy materialization for GitHub

Don't keep 76 repos hot. Show github/repos/_index.json and materialize a repo dir on first access.

Expected impact

• The Notion-by-title task should drop from N file reads → 1–2 file reads
• The Opus cost regression should flip on the same eval
• Cross-integration tasks (the strongest pitch) get an even larger lift since the agent doesn't burn turns on each integration's discovery
• Smaller models (Haiku, Sonnet) benefit even more — context savings are already 16–45%, this should push that further

Suggested split

This could be one PR or split:

• PR 1: indexes + LAYOUT.md (low-risk, additive)
• PR 2: semantic-key aliases (by-title, by-id)
• PR 3: state-grouped views + lazy GH materialization

Next step

Re-run the benchmark suite (single-integration reads + cross-integration tasks) after each PR to quantify the lift per fix. The benchmark itself becomes the marketing artifact.