feat(design-systems): give a design system a way to reach the session

Storing a design system never made a session aware of one. Rules get pushed
into every session by the SessionStart hook and returned by enter_project; a
design system had neither, so its standards were reachable only by an agent
that already knew to call resolve_design_system — the same silent failure as a
token nobody declares.

That gap was invisible while the operator's visual standards also lived in a
rulebook. Retiring that rulebook (which is what this unblocks) would have
deleted design guidance from every session with nothing to say so.

- services/design_systems.design_context() — the delivery side. Guidance is
  chain-merged ANCESTOR-FIRST: a child system holds only what it CHANGES, so
  its own guidance describes a departure from a house style it never restates,
  and the leaf alone is a fragment. Tokens are summarised (count + group
  names), not listed — a hundred declarations would crowd out the context they
  are meant to inform.
- enter_project returns `design_system`, null when the project has none.
- The SessionStart context gains a Design system block with pointers to the
  values, alongside the always-on rules.
- server.py's entity list gains Design system, including the negative: do NOT
  record one as a rulebook, because a token kept as prose cannot be resolved,
  inherited, rendered or checked.
- The rulebook-tier passage used "a design-system rulebook" as its worked
  example of a subscribed rulebook — it now teaches the opposite, plus a new
  "is this a rule at all?" test pointing at design systems, processes and
  snippets.
- using-scribe gains a section on building UI against the project's system.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UaYUaouG9jjhATyuxCKrQs

src/scribe/mcp/server.py

@@ -42,6 +42,18 @@ What each part is for, and when to reach for it:
 - Note: durable free-form knowledge — reference material, decisions, logs of
   what happened.
   No lifecycle, not actionable. Reach for one to CAPTURE something worth keeping.
+- Design system: the visual standards a project's UI is built from — design
+  tokens (name + value per mode) plus the prose a token table cannot hold
+  (aesthetic, voice, what is out of scope). Systems INHERIT: a child holds only
+  what it changes and the chain supplies the rest, so a family's house style and
+  one app's departures from it are the same structure at two depths. A project
+  points at one with set_project_design_system, and enter_project then hands it
+  back with the guidance chain-merged. Treat it as binding for UI work: reach
+  for a token (resolve_design_system / get_design_system_stylesheet) before
+  writing a colour, size, radius or duration by hand. Do NOT record a design
+  system as a rulebook — rules are for behaviour, and tokens kept as prose
+  cannot be resolved, inherited, rendered to a stylesheet, or checked against
+  code.
 - System: a per-project, reusable, self-describing subsystem/area. Associate any
   record (note, task, issue) with it via system_ids so research, build-work, and
   fixes for the same area line up, and recurring problem-spots surface. Manage
@@ -144,8 +156,8 @@ right altitude:
     subscribe_project_to_rulebook) — a reusable, THEMED module of general
     rules that binds only the projects which subscribe. Its rules must make
     sense for every project that could subscribe, never one specific project
-    (e.g. a design-system rulebook: design-specific but project-agnostic — no
-    rule names a single app).
+    (e.g. a code-review checklist, or a compliance regime a category of
+    projects shares — no rule names a single app).
   - Project rule (create_project_rule) — anything specific to ONE project.
 Both rulebook tiers are SHARED, so their rules stay general; the difference
 between them is REACH (all projects vs opt-in by theme), not generality. Rule
@@ -153,6 +165,15 @@ of thumb: names a specific project's files/paths/quirks -> project rule; a
 standard a CATEGORY of projects shares -> subscribed rulebook; a universal
 norm -> always-on rulebook. Coordinate with the operator on which home fits.
 
+Before writing a rule, check whether another entity already models the thing.
+A rule is prose an agent must remember and apply; the other entities are
+structure a tool can resolve, render and check. Visual standards are a DESIGN
+SYSTEM, not a rulebook — a token can be inherited, resolved per mode, rendered
+to a stylesheet and diffed against code, and none of that survives being
+written as a rule. A repeatable procedure is a PROCESS. Reusable code is a
+SNIPPET. Reach for a rule when the thing genuinely is a standing instruction
+about how to work, and nothing else can hold it.
+
 One thing NOT to do: don't bridge Scribe into a session by writing to the
 host's native memory. Rules are pull-only, so a fresh session won't reach for
 them unless its always-loaded context says to — but the bridge for that is the

src/scribe/mcp/tools/projects.py

@@ -17,6 +17,7 @@ keeps working.
 from __future__ import annotations
 
 from scribe.mcp._context import current_user_id
+from scribe.services import design_systems as design_systems_svc
 from scribe.services import milestones as milestones_svc
 from scribe.services import notes as notes_svc
 from scribe.services import projects as projects_svc
@@ -53,7 +54,13 @@ async def enter_project(project_id: int) -> dict:
 
     Returns a dict with keys: project, milestone_summary, applicable_rules,
     project_rules, subscribed_rulebooks, applicable_rules_truncated,
-    open_tasks, recent_notes.
+    open_tasks, recent_notes, design_system.
+
+    `design_system` is null unless the project points at one. When present it
+    carries the chain-merged guidance (the house style AND this project's
+    departures from it) plus a summary of the token set — treat it as binding
+    for any UI you write, and pull the values with resolve_design_system or
+    get_design_system_stylesheet before reaching for a literal.
     """
     uid = current_user_id()
     project = await projects_svc.get_project(uid, project_id)
@@ -74,9 +81,17 @@ async def enter_project(project_id: int) -> dict:
         uid, is_task=False, project_id=project_id,
         sort="updated_at", limit=5,
     )
+    # A project need not have one, and most installs won't — null is ordinary
+    # here, not a missing prerequisite.
+    design_system = None
+    if project.design_system_id:
+        design_system = await design_systems_svc.design_context(
+            uid, project.design_system_id,
+        )
 
     return {
         "project": project.to_dict(),
+        "design_system": design_system,
         "milestone_summary": milestone_summary,
         "applicable_rules": applicable["rules"],
         "project_rules": applicable.get("project_rules", []),

src/scribe/services/design_systems.py

@@ -282,6 +282,68 @@ async def resolve_design_system(
     return resolve_tokens(design_system_id, parents, tokens_by_system)
 
 
+async def design_context(user_id: int, design_system_id: int) -> dict | None:
+    """What a session needs to know about a design system, before it writes UI.
+
+    This is the DELIVERY side of a design system, and it exists because storing
+    one does not make a session aware of it. Rules get pushed into every session
+    by the plugin's SessionStart hook; a design system had no such channel, so
+    the standards were reachable only by an agent that already knew to go
+    looking — which is the same silent failure as a token nobody declares.
+
+    Guidance is chain-merged, ANCESTOR-FIRST, and that is the point rather than
+    a convenience. A child system holds only what it CHANGES, so its own
+    guidance describes a departure from a house style it never restates. Hand an
+    agent the leaf alone and it builds against a fragment, with no signal that
+    the rest exists.
+
+    Tokens are summarised, not listed: the count and the group names are enough
+    to know what the system covers, and the full set is one call away. Sending
+    a hundred token values into every session start would crowd out the context
+    it is meant to inform.
+
+    None when the caller may not read the system.
+    """
+    tokens = await resolve_design_system(user_id, design_system_id)
+    if tokens is None:
+        return None
+
+    async with async_session() as session:
+        system = await session.get(DesignSystem, design_system_id)
+        if system is None or system.deleted_at is not None:
+            return None
+        parents = await _parent_map(session, system.owner_user_id)
+        chain = ancestry(design_system_id, parents)
+        rows = (
+            await session.execute(
+                select(DesignSystem).where(DesignSystem.id.in_(chain))
+            )
+        ).scalars().all()
+
+    by_id = {s.id: s for s in rows}
+    return {
+        "id": system.id,
+        "title": system.title,
+        "description": system.description or "",
+        # Outermost ancestor first, so the reader meets the house style before
+        # the app's departures from it.
+        "inherits_from": [
+            by_id[sid].title for sid in reversed(chain[1:]) if sid in by_id
+        ],
+        "guidance": [
+            {
+                "design_system_id": sid,
+                "title": by_id[sid].title,
+                "guidance": (by_id[sid].guidance or "").strip(),
+            }
+            for sid in reversed(chain)
+            if sid in by_id and (by_id[sid].guidance or "").strip()
+        ],
+        "token_count": len(tokens),
+        "token_groups": sorted({t.group_name for t in tokens if t.group_name}),
+    }
+
+
 async def update_token(
     user_id: int, token_id: int, **fields: object
 ) -> DesignToken | None:

src/scribe/services/plugin_context.py

@@ -22,6 +22,7 @@ from sqlalchemy import select
 
 from scribe.models import async_session
 from scribe.models.rulebook import RulebookTopic
+from scribe.services import design_systems as design_systems_svc
 from scribe.services import knowledge as knowledge_svc
 from scribe.services import notes as notes_svc
 from scribe.services import projects as projects_svc
@@ -837,6 +838,37 @@ async def build_session_context(
                 f"Goal: {goal[:200]}" if goal else "",
                 f"Open todo tasks: {open_count}",
             ]
+
+            # A design system binds the same way a rule does, and until this
+            # existed it had no push channel — the standards were reachable only
+            # by an agent that already knew to look for them. Summary only: the
+            # token VALUES are a tool call away, and pasting a hundred of them
+            # into every session would crowd out the context they inform.
+            if project.design_system_id:
+                design = await design_systems_svc.design_context(
+                    user_id, project.design_system_id,
+                )
+                if design:
+                    inherits = (
+                        " (inherits " + " › ".join(design["inherits_from"]) + ")"
+                        if design["inherits_from"] else ""
+                    )
+                    groups = ", ".join(design["token_groups"])
+                    lines += [
+                        "",
+                        f"## Design system: {design['title']} "
+                        f"(id {design['id']}){inherits}",
+                        f"{design['token_count']} tokens"
+                        + (f" across {groups}" if groups else "")
+                        + ". This project's UI is built from these, not from "
+                        "literals — reach for a token before writing a colour, "
+                        "size, radius or duration by hand.",
+                        f"Values: `resolve_design_system({design['id']})` · "
+                        f"stylesheet: `get_design_system_stylesheet({design['id']})` "
+                        f"· the prose (aesthetic, voice, where the accent may "
+                        f"appear): `enter_project` returns it, or "
+                        f"`get_design_system({design['id']})`.",
+                    ]
     elif unbound_repo:
         lines += [
             "",