docs: define Beacon as a time-to-competence interface

[ctharvey]

Summary

Refines Beacon around a clearer architectural objective:

Beacon is an adaptive onboarding interface that minimizes Time-to-Competence for an authorized consumer.

A Beacon should not merely expose stored knowledge. It should help another intelligence—human or artificial—become useful on a topic, project, system, or organization as quickly as possible.

Core philosophy

The new docs/beacon-time-to-competence.md establishes that Beacon should optimize for transferring understanding rather than maximizing raw data exposure.

A first interaction should answer:

1. What is this?
2. Why does it exist?
3. What should I understand first?
4. What is currently true?
5. What changed recently?
6. What should I explore next?
7. Where is the supporting evidence?

The intended onboarding flow is:

Discover Beacon
    ↓
Identity
    ↓
Purpose
    ↓
Core Concepts
    ↓
Current State
    ↓
Recent Changes
    ↓
Suggested Next Topics
    ↓
Evidence on demand

Architectural model

Beacon remains an addressable, permissioned Semantic Object, but that formula now describes the mechanism rather than the purpose.

Semantic Object
+ access/disclosure policy
+ addressability
+ revision/freshness metadata
+ optional signature
= Beacon

The purpose is adaptive knowledge transfer.

The same underlying Semantic Object may present different orientation packages to:

• a first-time LLM;
• a returning agent that only needs recent changes;
• an expert seeking implementation detail;
• a human onboarding to a project;
• an automation requesting narrow machine-readable state.

Added

• docs/beacon-time-to-competence.md

  • defines Time-to-Competence as Beacon's primary architectural objective
  • establishes orientation before detail
  • distinguishes competence from completeness
  • introduces adaptive onboarding and progressive disclosure
  • introduces teaching metadata such as canonical terminology, learning order, misconceptions, and architectural landmarks
  • keeps evidence and traceability first-class

• docs/beacon-as-permissioned-semantic-object.md

  • unifies Beacon's capability-contract model with structured Semantic Objects
  • defines one object with multiple audience-specific Beacon surfaces
  • applies permissions at the View and capability level
  • covers addressability, discovery, revisions, change events, evidence receipts, signatures, subscriptions, and provider independence

• docs/beacon-design-review-response.md

  • records architecture review conclusions
  • reframes Beacon as a capability contract
  • clarifies declared versus observed knowledge

• docs/origin-and-design-evolution.md

  • records the evolution from public Menhir endpoint to Agent-to-Project capability contract

• docs/provider-maturity-model.md

  • defines manifest → docs → Git → local index → temporal Semantic Object provider tiers

• docs/beacon-doctor-roadmap.md

  • adds validation, inspection, drift detection, CI, and self-maintenance tooling

• docs/security-and-visibility.md

  • defines public, authenticated, organization, maintainer, and local visibility

• docs/knowledge-kinds.md

  • separates declared, observed, and derived knowledge

Updated thesis

Beacon is provider-independent and transport-independent:

• Time-to-Competence is the product and architecture objective
• capability contracts define what consumers may ask or observe
• Semantic Object schemas define the available structured state
• disclosure profiles define which Views and capabilities are exposed
• MCP is one transport, not the concept itself
• static and Git-aware providers can implement progressively richer subsets
• Menhir can provide temporal Views, assertion lineage, historical reconstruction, and object-level change semantics

Permissions, transport, subscriptions, and serialization remain necessary implementation concerns. They serve the larger goal: helping an authorized intelligence become competent quickly without sacrificing evidence, provenance, or control.