The studio manifest: config.toml binds the installation (slice 1 of the installation architecture)

[aarontrowbridge]

Important

Problem — Amicode's installation layout is implied but never declared: four root-bridging symlinks (~/.amico/{vaults,problems,runs,julia} → ~/armonia/data/*), research capital inside the dotdir (ledger/, profile.json), the catalog inside a team vault, and path knowledge duplicated as env vars and hardcoded defaults across the extension, amico-run, and telaio. Three half-migrations have left husks. Every new consumer re-derives where things live.

Approach — The manifest: one config file (~/.amicode/config.toml) declaring the binding — studio_root, the ordered vault mount stack, catalog, ledger, harness, pack roots, tenant — read by every consumer with today's-path fallbacks. NO file moves in this slice; absence of the manifest means exactly today's behavior. Ships with amicode doctor, the validation surface that makes the binding checkable (and later, the fleet health check's data source).

Scope — in: manifest schema + reader library, consumer adoption (extension boot, amico-run, telaio store default), doctor, parity when absent · out: relocations, symlink retirement, the dotdir rename + alias, workspace generation (later slices of the same design-of-record).

Acceptance Criteria

• A manifest at ~/.amicode/config.toml validates (strict shape: studio_root, ordered mounts with kind+mode, catalog/ledger/harness paths, tenant) and one reader library owns its parsing — no consumer re-parses
• The extension, amico-run, and telaio resolve their roots through the manifest, falling back to today's paths (incl. following the existing symlinks) when it is absent — behavior identical, proven by the existing suites with no fixture changes
• Hermetic overrides still win: test/env paths override the manifest (the suites stay hermetic)
• amicode doctor validates the binding: paths exist, mounts readable, exactly one rw personal mount, and reports drift as a table with reason codes
• doctor flags (does not fix) the known drift: catalog not under the studio root, ledger under the dotdir — the relocation slices' to-do list

Testing Decisions

Extend the extension prep-integration suite with manifest fixtures (present/absent/malformed); amico-run's config resolution gains table tests over the fallback ladder; doctor gets its own suite against fixture trees. No new test surface beyond doctor.

Key Decisions

• The manifest is the single source of binding; env-var overrides remain as hermetic escapes, documented as test-only.
• Absent manifest ⇒ legacy behavior exactly (never brick — the WS1 fallback doctrine).
• The schema lives in @amicode/schema (one validator, the established pattern) — kind amicode-config, JSON-schema-validated TOML.
• Relocations, alias, and workspace generation are explicitly later slices; this slice moves nothing.

Constraints & Invariants

• No behavior change for any existing install without a manifest (parity-gated).
• The manifest never carries secrets (keyring stays per-machine; the config names roots, not credentials).
• Fleet scripts keep working untouched (they read the symlinked paths, which still exist).

Prior Art

• The WS1 pack-root resolution (ordered roots, precedence, fallback) — the same grammar, one level up.
• The vault mount-stack resolver (precedence + write-routing) whose declaration this formalizes.
• amico-server.sh's path resolution ladder — the class of logic the manifest replaces.

Source

Design-of-record: vault spec note spec-20260817-120000-installation-architecture (installation architecture — three planes, one manifest). Design session 2026-08-17.