Skip to content

ADR 0131: Setup never offers to adopt existing docs — and "docs tree" retires with it

Placement amendment: The fresh map now lands at discern/map/. Setup's no-adoption rule and the separation from a project's own docs/ remain unchanged.

Status: accepted; amends ADR 0100

Context

§

ADR 0100 separated the two artifacts that had shared the name "docs" — the project's own documentation and the tree discern maintains, the map — and reduced setup's collision machinery to one consent question: keep the map in its own folder, or point it at the project's existing docs. ADR 0120 then promoted "map" to the verb and the address (map/), retiring the docs spelling from every contract position.

The question survived both decisions, and it aged badly:

  • It re-teaches the conflation the rename ended. The first thing a new user hears about the map is an offer to point it at their human-curated documentation — the restructure-someone's-website failure mode ADR 0100 made impossible by construction, reintroduced as a suggestion at first contact.
  • It spends a consent slot on the wrong default. The consent conversation is deliberately short (courier agents prune long messages); a question implies a live choice, and adoption is the right choice for almost nobody. A project that truly wants the map discipline over its real docs can still configure that deliberately.
  • The vocabulary survived in the walls. "docs tree" persisted across comments, test names (29 map-browser tests still opened with the retired docs verb), early landing-page drafts, and the map's own installer pages.

Decision

§
  • Setup reassures; it never offers. When the project has its own docs/ folder, the consent message states that it stays untouched and that the map is discern's separate tree at its own home — a statement, not a question. The --map coda after the message fence retires with it: the consent surface never mentions the flag.
  • [map].dir remains address configuration, not an adoption channel. The flag and the key still accept any directory, but no shipped surface suggests pointing them at human-curated documentation.
  • The phrase "docs tree" retires from every authored surface. The tree is the map; a literal directory stays describable as "the docs/ folder". The development-vocabulary guard grows a class-level check (tests/dev_vocab_guard_test.ts) banning the phrase outside frozen records — historical ADRs, archived briefs, and historical install fixtures.

Consequences

§
  • ADR 0100's "offered as a question during setup" consequence is superseded; its map identity, namespace-default, and eager-scaffold decisions stand unchanged (an amendment note marks it there).
  • The consent message now names the map's real default home (map/) in its footprint bullet — it previously placed the map inside the discern/ folder, a leftover of the pre-ADR-0120 default.
  • A future decision to support deliberate adoption (documentation-migration tooling, say) must clear the guard deliberately — new vocabulary and a new consent design, not a revival of the old question.

Alternatives considered

§
  • Keep the question, reword it — any phrasing that offers adoption at first contact still teaches the conflation; the offer, not the wording, was the defect.
  • Drop the --map flag too — the address must stay configurable (ADR 0120 kept it so); the defect was the suggestion, not the capability.
  • Guard only the offer, not the phrase — the behavioral tests pin the offer's absence, but the phrase is how the concept re-enters prose; both are guarded.
choose openEsc close