0004 — companies.sh install-only for v1

• Date: 2026-04-30
• Status: Accepted

Context

companies.sh is a public directory of company manifests. Round-tripping (fork in, publish back) is a clean story but a real chunk of work — schema discipline, GitHub OAuth, PR creation flow.

Decision

v1 supports installing/forking only. Publish-back is deferred until we know what shape exported manifests should take in practice.

Alternatives considered

• Build both. Extra weeks, and we'd be guessing at the export schema before we have real workspaces to learn from.
• Build a "download manifest JSON" button. Half-shipping. Users would treat it as the contract and we'd be locked in.

Consequences

• The internal manifest schema can evolve freely until publish-back lands.
• When users ask "how do I share my company?", the v1 answer is "you can't yet." Don't half-ship a JSON export.
• The importer is the only flow that has to be solid for v1. Make it idempotent — re-forking should add new things without touching existing rows.