docs(theme-selector): settle inheritance as model-and-override in the spec

Craig settled the inheritance question: model it rather than flatten it. Each face's resolved color shows in the table marked as inherited, the mock preview paints every face with its effective color, and overriding any face is one assignment that flips it from inherited to explicit. Export keeps the :inherit relationship for faces left alone and writes explicit attributes only for the ones overridden. Seeded defaults open showing org's real cascade. That clears one of the three open decisions; inventory split and picker timing remain.

1 files changed, 29 insertions, 22 deletions

diff --git a/docs/design/theme-selector-package-faces-spec.org b/docs/design/theme-selector-package-faces-spec.org
index 60c4e9c5..69241e0a 100644
--- a/docs/design/theme-selector-package-faces-spec.org
+++ b/docs/design/theme-selector-package-faces-spec.org
@@ -10,9 +10,10 @@ package-specific faces, built one application at a time. v1 apps: org-mode
 (incl. org-agenda), magit, elfeed. Codex review incorporated (2026-06-07): added
 implementation phases, acceptance criteria, the package-face inventory source
 (hybrid, split), and state/export semantics. Rubric now =Ready with caveats=.
-Three opens remain for Craig: confirm the inheritance representation
-(absolute-default + opt-in inherit), confirm hybrid-and-split inventory (vs
-curated-only v1), and the custom color picker timing.
+Inheritance resolved (Craig, 2026-06-07): model it, show each face's resolved
+color in the table + preview, override what looks bad. Two opens remain for
+Craig: confirm hybrid-and-split inventory (vs curated-only v1), and the custom
+color picker timing.
 
 * Background — the three tiers
 
@@ -362,9 +363,7 @@ reflect these; this records the decisions):
    *every* package they have); only the rich preview is missing, replaced by a
    swatch-in-context fallback. Bespoke previews ship for org, magit, elfeed.
 
-* Inheritance representation (answer to Craig's question)
-
-Craig asked how inheritance would be represented. Proposal:
+* Inheritance representation (decided)
 
 Each face carries an optional =inherit= field naming another face (or =null=).
 The face's own =fg/bg/bold/italic= are *overrides* layered on top of what it
@@ -377,22 +376,30 @@ inherits.
 // exports as: (org-agenda-date-today ((t (:inherit org-agenda-date :weight bold))))
 #+end_src
 
-In the tool, an inheriting row shows an "inherits <face>" chip; attributes left
-unset render greyed (they come from the parent) until the user overrides one.
-The converter writes =:inherit PARENT= followed by only the overridden
-attributes.
-
-*Recommendation: default to absolute values, offer inherit as opt-in.* Emacs
-face inheritance surprises people — an inherited background or weight rides
-along silently — so seeding every face with absolute attributes is the
-predictable default. Inheritance is available for the cases where a cascade is
-genuinely wanted (all heading levels off one base; agenda-date variants off
-=org-agenda-date=), expressed with the =inherit= field above. This keeps the
-common path obvious and the export deterministic, while still letting a user
-model the relationships org itself uses.
-
-Decision pending Craig's confirm: absolute-default with opt-in inherit (above),
-or model inheritance for the face families that have it out of the box.
+*Decision (Craig, 2026-06-07): model inheritance, show the resolved result,
+override what looks bad.* The point is to see what a face ends up looking like
+when it inherits, judge it in the preview, and fix only the ones that look
+wrong:
+
+- Each face's *effective* color is resolved through its inherit chain and shown
+  in its table row, visibly marked "inherited from <face>" so it reads as
+  not-explicitly-set. The face's own =fg/bg/bold/italic= are overrides layered
+  on top.
+- The mock preview on the right renders every face with its effective color, so
+  inherited faces are judged in context, not in the abstract.
+- Overriding is one action: assign a color (or toggle weight) and the row flips
+  from inherited to explicit (=source: "user"=), shown at once in the table and
+  preview.
+- Export writes =:inherit PARENT= for faces left inherited (carrying the
+  relationship, so they follow the parent the theme also sets) and explicit
+  attributes for the ones overridden — never a frozen copy of an inherited
+  color.
+
+Seeded defaults express the inherit relationships org itself uses out of the box
+(heading levels off a base, =org-agenda-date= variants off =org-agenda-date=,
+=org-code= / =org-verbatim= off =fixed-pitch=), so the table opens showing
+org's real cascade, which the user then tunes. Inheritance cycles resolve to no
+inheritance.
 
 * Custom color picker (proposal)