WS-006: Why build-the-product knowledge will be read from the portal

Status	Accepted direction — mechanism not implemented
Date	2026-08-05
Sources	inbox capture 02; this proposal’s Artifact 4

Context

Today humans and AI agents learn how to build ER by opening private repos: CLAUDE.md, docs/, PROGRESS.md. This portal aggregates principles and ADRs so there is a single place to read. The next step would be agents preferring this published surface over local files.

Problem

Local files are correct for offline binary work, but they fragment onboarding: you must already know which repo to open. Published metadata (catalog, OpenAPI) already proved that knowledge can be a contract. Build-knowledge has not crossed that line yet.

Decision (direction only)

Future state: contributors and AI read build-the-product knowledge primarily from developer.engineeringruntime.com (principles, ADRs, day-one), the same way external systems read contracts from api..

Not now. Ship no fetch-from-portal mechanism in the runtime or agent until both preconditions are true:

1. Gate strength — today’s login is client-side obscurity with a shared credential. Inadequate for programmatic access. Need Cloudflare Access (or equivalent) or a published-contract path with real auth.
2. Runtime rules — engineering-runtime/CLAUDE.md requires reading local docs/ and treats .claude/skills/PROGRESS.md as authority on current state. Redirecting that to a network fetch is the same class of trade as 2026-08-05-runtime-reads-api-contract-from-api-host (planning-only) and must be decided the same way.

Alternatives considered

Alternative	Why not now
Implement portal-fetch in agents immediately	Gate + PROGRESS authority preconditions false
Move all docs out of the runtime repo	Breaks self-contained binary checkout (Option A rejected)
Stay repo-only forever	Leaves the bottleneck the portal exists to remove

Consequences

• This ADR records intent while the aggregation (Option D) ships
• Do not treat the portal as the runtime’s SSOT until a follow-up proposal flips the preconditions
• Aggregation + hand-written WS ADRs are the bridge, not the end state