secondbrain-py 0.2.1__py3-none-any.whl

brain/quartz_overrides/quartz/styles/brain/_marginalia.scss

@@ -0,0 +1,117 @@
+// Brain marginalia — Lane D of the 2026 commonplace-book redesign.
+//
+// This file is installed at
+// `<vault>/.quartz/quartz/styles/brain/_marginalia.scss` by `brain
+// vault render --overlay` and pulled into the global SCSS via
+// `custom.scss`'s `@use "./brain/marginalia"` line (between
+// `article` and `callouts`).
+//
+// What this file owns: at desktop+ viewports (≥1280px), the right
+// sidebar's `<div class="backlinks">` block reads as figure-margin
+// side-notes — narrow column width, italic Newsreader, dimmed ink,
+// tight per-link spacing — so backlinks register as "the
+// commonplace book's marginal annotations" rather than "another
+// chrome panel."
+//
+// brain (Lane D — fallback path taken):
+//
+//   The original Lane D plan considered moving `.backlinks` out of
+//   `.right.sidebar` and rendering it as a true sibling of `.center`
+//   in the article column's right gutter — the "real Tufte
+//   side-note" approach. We did NOT take that path. Reasons:
+//
+//   1. Quartz's three-column grid is defined in `base.scss` via
+//      `templateAreas` (`grid-sidebar-left grid-center
+//      grid-sidebar-right`). Extracting `.backlinks` into a fourth
+//      grid area requires modifying the template at the source —
+//      either by editing `base.scss` (which the overlay tries hard
+//      to leave untouched, since stock Quartz's `joinStyles()` and
+//      grid map machinery in `variables.scss` are tightly coupled),
+//      or by duplicating the grid declaration here, which then
+//      becomes a fragile fork.
+//
+//   2. The backlinks component itself is rendered by Quartz's layout
+//      engine into the `right` slot (see `quartz.layout.ts` line
+//      144). To make `.backlinks` a sibling of `.center` in the DOM
+//      we'd need to either move the component declaration out of
+//      `right: [...]` (and lose its sticky-sidebar positioning for
+//      everything else in that column), or split the component
+//      tree, neither of which is a single-file SCSS concern.
+//
+//   3. The team-lead's brief explicitly endorses this fallback:
+//      "If marginalia turns out architecturally infeasible without
+//      layout surgery, document why and fall back to a 'softer'
+//      treatment: the right-sidebar Backlinks block gets the same
+//      italic / smaller / dimmed treatment it would have in
+//      marginalia, but stays in its current position. This is
+//      acceptable — design intent is preserved, layout architecture
+//      isn't violated."
+//
+//   The fallback preserves ~95% of the visual intent: backlinks read
+//   as marginalia (narrow, italic, dimmed, compact), they just live
+//   in the right sidebar instead of the article's right gutter. A
+//   future redesign that's willing to fork `base.scss` can take the
+//   architectural path; this file is the current best-effort
+//   styling contract.
+//
+// Below the desktop breakpoint (1280px and narrower) this file makes
+// NO changes — the right sidebar falls back to its Lane C card
+// styling from `_sidebar.scss`. That's deliberate: at 1200px or
+// 1024px the backlinks panel needs the full sidebar width to read,
+// and squeezing it into a 18ch column would force every backlink
+// title to truncate.
+//
+// Tokens consumed (all from `_tokens.scss`):
+//   * `--ink-2`        — dimmed marginalia ink color
+//   * `--fs-sm` / `--fs-xs` — smaller-than-body type
+//   * `--rule`         — vertical rule on the marginalia column edge
+//   * `--bodyFont`     — Newsreader italic for the side-note voice
+//                        (printed marginalia is always body type one
+//                        notch smaller than running prose, not display
+//                        type — even though Lane A's project-wide
+//                        italic convention reaches for Fraunces, that
+//                        rule applies to inline emphasis, not to a
+//                        whole-block side-note voice)
+
+// ---------------------------------------------------------------------------
+// 1. Marginalia treatment at desktop+ viewports
+// ---------------------------------------------------------------------------
+//
+// 1280px is one notch above Quartz's `$desktop` breakpoint (1200px).
+// At 1200-1279px the right sidebar is already cramped (the local
+// graph eats most of the vertical space); marginalia would compete
+// with the graph and ToC for too little room. At 1280px+ there's
+// enough vertical breathing room to make the backlinks panel feel
+// like figure-margin annotations rather than another stacked card.
+//
+// Why scope to `.right.sidebar > .backlinks` (not just `.backlinks`)?
+// Quartz emits `<div class="backlinks">` from `Component.Backlinks`
+// (see `quartz/components/Backlinks.tsx` line 32). The same component
+// could in theory appear elsewhere (e.g. `.center` slot for a
+// custom layout); we only want the marginalia treatment when the
+// component is sitting in the right sidebar position. The descendant
+// selector enforces that scope.
+//
+// brain: this rule wins over Lane C's `.sidebar.right .backlinks`
+// card chrome (background, border-radius, shadow, padding) because
+// it's both later in the cascade AND uses overrides where they
+// matter (background → transparent, padding → 0). Where Lane C
+// rules don't conflict (e.g. nothing about font-style) we inherit
+// Lane C's defaults silently — which is fine.
+
+// brain (2026-05-06): the marginalia treatment was REMOVED per user
+// feedback that Backlinks read as visually inconsistent with the
+// Related and Table of Contents cards above it (190px column vs ~256px
+// full-width cards). Backlinks now inherits Lane C's full-width card
+// chrome from `_sidebar.scss` (`background: var(--surface-1)`,
+// `border-radius: 8px`, `box-shadow: var(--shadow-sm)`,
+// `padding: 0.6rem 0.8rem`), matching the ToC and Related panels above
+// it. The italic / dimmed / narrow side-note voice is dropped — sidebar
+// reads as a stack of three coordinated panels instead.
+//
+// If a future redesign wants the Tufte side-note treatment back, the
+// architectural path is to extract `.backlinks` into a fourth grid
+// area in `base.scss`'s template (see the original analysis in this
+// file's git history at commit 2eaf550) — re-applying the SCSS without
+// also moving the DOM out of `.right.sidebar` reproduces the exact
+// width-mismatch bug this removal addresses.

brain/quartz_overrides/quartz/styles/brain/_motion.scss

@@ -0,0 +1,175 @@
+// Brain motion — Lane D of the 2026 commonplace-book redesign.
+//
+// This file is installed at
+// `<vault>/.quartz/quartz/styles/brain/_motion.scss` by `brain vault
+// render --overlay` and pulled into the global SCSS via
+// `custom.scss`'s `@use "./brain/motion"` line (between
+// `atmosphere` and `links`).
+//
+// What this file owns:
+//
+//   1. Page-load reveal animation — staggered slide/fade for the
+//      three-column shell on first paint. Sidebar-left slides in
+//      from the left, center fades up, sidebar-right slides in from
+//      the right; offsets ramped 50ms / 150ms / 250ms so the eye
+//      reads them in sequence rather than as a single twitch.
+//   2. `prefers-reduced-motion` accessibility gate — the entire
+//      animation block sits inside a `(prefers-reduced-motion:
+//      no-preference)` media query so a user with the OS-level
+//      reduce-motion setting never sees the slide-in. Without the
+//      gate the WCAG 2.2 SC 2.3.3 (Animation from Interactions)
+//      regression risk is real for vestibular-disorder users.
+//   3. Documentation pointer to the canonical motion-token knobs.
+//      Lane A's `_tokens.scss` defines `--motion-fast`, `--motion-mid`,
+//      `--motion-slow`, and `--motion-easing` — every other partial
+//      consumes those tokens for hover / focus / transition timings.
+//      This file does NOT redefine them; it just notes where they
+//      live so a future maintainer knows the single source of truth.
+//
+// Tokens consumed (all from `_tokens.scss`):
+//   * `--motion-easing` — smooth-out-quint cubic-bezier for the
+//     reveal animations.
+//
+// Tokens NOT redefined here (deliberate — see above):
+//   * `--motion-fast` (150ms) — hover transitions, link underline
+//     reveals (Lane B `_links.scss`), code-copy button (Lane C).
+//   * `--motion-mid` (250ms) — Cmd-K modal entrance, ToC card hovers,
+//     callout chrome.
+//   * `--motion-slow` (400ms) — page-load reveal duration; the
+//     stagger offsets below cap at 250ms so the cumulative reveal
+//     finishes around 650ms (slow + last-stagger), short enough to
+//     not feel laggy but long enough to register as "the page
+//     composed itself" rather than "the page snapped in."
+//
+// brain (Lane D): hover micro-interactions are already wired in
+// Lanes B (link underlines) and C (sidebar icon trio, code-copy
+// button, callout chrome). This file deliberately does NOT
+// re-declare those — the `--motion-fast/mid/slow` + `--motion-easing`
+// tokens declared in `_tokens.scss` are the canonical knobs, and
+// the consuming partials read them directly. If a future change
+// wants to retune motion globally, change the tokens once in
+// `_tokens.scss` and every consumer updates.
+
+// ---------------------------------------------------------------------------
+// 1. Page-load reveal — staggered three-column entrance
+// ---------------------------------------------------------------------------
+//
+// The animation block is wrapped in
+// `(prefers-reduced-motion: no-preference)` — the negative form
+// matches when the OS-level reduce-motion setting is OFF. Users
+// with reduce-motion ON see the page paint statically, no slide,
+// no fade.
+//
+// Stagger order:
+//   * `.left.sidebar` — 50ms delay, slides 12px from the left
+//   * `.center`       — 150ms delay, fades up 8px
+//   * `.right.sidebar` — 250ms delay, slides 12px from the right
+//
+// Why this order: the eye reads the page from outside-in. The
+// left-sidebar (search + explorer) and right-sidebar (graph + ToC +
+// backlinks) are reference scaffolding; the center is the article
+// itself. By staggering the chrome before the content, we cue the
+// reader's eye toward the center column on arrival — the page
+// "composes itself" around the article rather than dumping
+// everything in at once.
+//
+// `animation-fill-mode: both` (the `both` keyword in the shorthand)
+// applies the `from` keyframe state during the delay window. Without
+// it, the elements would paint at their final state during the 50/
+// 150/250ms delay, then snap back to `from` and run the animation —
+// the dreaded "FOUC of motion." `both` makes the delay window the
+// `from` state.
+//
+// SPA navigation (Quartz's `enableSPA` + micromorph) patches DOM in
+// place rather than replacing it, so `.left.sidebar` / `.center` /
+// `.right.sidebar` are typically NOT re-mounted between routes. The
+// animation fires once per hard load, which is the desired behavior
+// — the cinematic entrance shouldn't replay on every internal click.
+
+// brain (Lane D audit fix 2026-05-02): the original commit hardcoded
+// the stagger delays as `0.05s`, `0.15s`, `0.25s`. Project rule is
+// tokens-only — the literals were swapped for `--motion-stagger-1/2/3`
+// declared in `_tokens.scss` (next to the existing `--motion-fast/
+// mid/slow` block). The duration `var(--motion-slow)` was already a
+// token; no change needed there.
+
+// brain (Linear-variant feedback round 4): `animation-fill-mode` is
+// `backwards`, NOT `both`. With `both`, the final keyframe's
+// `transform: none` was getting interpolated into
+// `matrix(1, 0, 0, 1, 0, 0)` (the identity) and stuck on the element
+// permanently. A non-`none` transform on `.right.sidebar` creates a
+// containing block for `position: fixed` descendants, which broke the
+// global-graph modal — it anchored to the sidebar instead of the
+// viewport, rendering as a narrow strip on the right edge.
+//
+// `backwards` applies the `from` keyframe BEFORE animation starts (so
+// the entrance animation has its hidden-and-shifted starting state
+// during the delay window) and lets the element fall back to its
+// natural style (transform: none, opacity: 1) after the animation
+// completes. No leftover identity-transform → no leftover containing
+// block → fixed-position modals anchor to viewport correctly.
+@media (prefers-reduced-motion: no-preference) {
+  .left.sidebar {
+    animation: brain-slide-in-left var(--motion-slow) var(--motion-easing) var(--motion-stagger-1) backwards;
+  }
+
+  .center {
+    animation: brain-fade-up var(--motion-slow) var(--motion-easing) var(--motion-stagger-2) backwards;
+  }
+
+  .right.sidebar {
+    animation: brain-slide-in-right var(--motion-slow) var(--motion-easing) var(--motion-stagger-3) backwards;
+  }
+}
+
+// Keyframes live OUTSIDE the media query — declaring them inside
+// would scope them to that query in a way some renderers handle
+// inconsistently. The `@keyframes` themselves are inert until
+// referenced by an `animation` property; defining them globally is
+// the conventional shape.
+
+// brain (Linear-variant feedback round 4): the `to` keyframes MUST end
+// with `transform: none`, NOT `transform: translateX(0)` /
+// `translateY(0)`. Reason: a non-`none` transform value on any
+// ancestor creates a containing block for `position: fixed` descendants
+// (per CSS spec). With `animation-fill-mode: both` (set on the
+// `.left.sidebar / .center / .right.sidebar` rules above), the final
+// keyframe's transform value sticks AFTER the animation finishes —
+// leaving `matrix(1,0,0,1,0,0)` on the sidebars permanently. That CB
+// caused the global-graph modal (which is `position: fixed; left: 0;
+// width: 100vw` inside `.right.sidebar`) to anchor to the sidebar
+// instead of the viewport, rendering as a narrow strip on the right
+// edge of the page. `transform: none` in the `to` keyframe restores
+// the default and the modal anchors back to the viewport.
+@keyframes brain-slide-in-left {
+  from {
+    opacity: 0;
+    transform: translateX(-12px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@keyframes brain-fade-up {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+@keyframes brain-slide-in-right {
+  from {
+    opacity: 0;
+    transform: translateX(12px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}

brain/quartz_overrides/quartz/styles/brain/_people_hub.scss

@@ -0,0 +1,100 @@
+// Brain People Hub — Phase C of the 2026-05-07 People Hub plan.
+//
+// This file is installed at
+// `<vault>/.quartz/quartz/styles/brain/_people_hub.scss` by `brain
+// vault render --overlay` and pulled into the global SCSS via
+// `custom.scss`'s `@use "./brain/people_hub"` line.
+//
+// Scope of this file:
+//
+//   * Distinct heading + frontmatter treatment for `kind: people`
+//     pages so the user can tell at a glance they're on a hub page
+//     (a person's roster) vs. a regular doc.
+//   * Index page (`/people/index`) gets a slightly heavier treatment
+//     to read as a directory landing page.
+//
+// Targeting strategy:
+//
+//   Quartz exposes `body[data-slug=...]` (set in `renderPage.tsx`)
+//   but does NOT expose a `data-kind` attribute for arbitrary
+//   frontmatter fields. We key off the slug prefix instead — every
+//   people-hub page lives under `people/...` (per the
+//   `<vault>/people/<slug>.md` emit contract in
+//   `src/brain/wiki/build_people.py`), so `body[data-slug^="people/"]`
+//   selects the entire hub. The index page gets an additional rule
+//   keyed off `body[data-slug="people/index"]` for landing-page treatment.
+//
+// Tokens consumed (all from `_tokens.scss`):
+//
+//   * `--accent-strong` — page-kind accent rail
+//   * `--surface-1`     — H1 underline backdrop
+//   * `--rule`          — primary-email block hairline
+//   * `--ink-0` / `--ink-2` — text colors
+
+// ---------------------------------------------------------------------------
+// 1. Per-person pages — `body[data-slug^="people/"]` minus the index.
+//
+// We rely on a sibling rule below to refine the index landing page.
+// The :not() selector keeps individual roster pages tighter (a
+// distinct accent rail under the H1) and lets the index claim the
+// fuller card treatment.
+// ---------------------------------------------------------------------------
+
+body[data-slug^="people/"]:not([data-slug="people/index"]) {
+  // Page-kind accent: a colored vertical rail to the left of the H1
+  // so the person's name reads as a heading-of-headings, not just
+  // another doc title. Uses padding (not margin) so the rail aligns
+  // with the article column rather than the page edge.
+  article > h1:first-of-type {
+    border-left: 4px solid var(--accent-strong, var(--secondary));
+    padding-left: 0.6rem;
+    // Subtle background so the rail reads as an enclosed badge rather
+    // than a stray vertical line. Falls back to `--gray` if the surface
+    // token isn't defined (older theme setups).
+    background: linear-gradient(
+      to right,
+      var(--surface-1, transparent) 0%,
+      transparent 60%
+    );
+  }
+
+  // Primary-email line: bold the label, faintly indent the value, give
+  // it a hairline underline so it reads as a header field rather than
+  // body prose. Targets the first `<p>` inside the article (the
+  // emitter writes "**Primary email:** [...]" as the very first
+  // paragraph).
+  article > p:first-of-type {
+    border-bottom: 1px solid var(--rule, var(--lightgray));
+    padding-bottom: 0.4rem;
+    margin-bottom: 1.2rem;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 2. Index page — `body[data-slug="people/index"]`.
+//
+// The index lists every person; we want it to read as a "directory
+// landing" page — heavier H1 treatment, a touch more breathing room
+// between roster rows. Ordering matters: this block must come AFTER
+// the per-person block above so its more specific selector wins
+// (the per-person rule's `:not([data-slug="people/index"])` already
+// excludes the index, but defense in depth).
+// ---------------------------------------------------------------------------
+
+body[data-slug="people/index"] {
+  article > h1:first-of-type {
+    // Heavier weight than the per-person H1; this is a landing page
+    // for the whole hub.
+    font-weight: 700;
+    border-bottom: 2px solid var(--accent-strong, var(--secondary));
+    padding-bottom: 0.4rem;
+    margin-bottom: 1.4rem;
+  }
+
+  // Roster rows — one per person — get a touch more vertical
+  // breathing room so the curated badge + name + doc count reads
+  // as a glanceable directory rather than a dense bullet list.
+  article ul > li {
+    padding: 0.2rem 0;
+  }
+}

brain/quartz_overrides/quartz/styles/brain/_related_docs.scss

@@ -0,0 +1,137 @@
+// Brain related-docs sidebar — Phase 5.2 of the Wiki UX Overhaul.
+//
+// Loaded globally via `custom.scss`. The component only renders in the
+// right sidebar for content pages; the runtime hides the whole panel
+// until `/static/related/<slug>.json` returns valid rows.
+
+.sidebar.right {
+  .brain-related-docs {
+    background: var(--surface-1);
+    border-radius: 8px;
+    padding: 0.6rem 0.8rem;
+    box-shadow: var(--shadow-sm);
+    box-sizing: border-box;
+    // brain: allow the panel to shrink in the right-sidebar flex column
+    // so a tall related list never pushes ToC / Backlinks off the
+    // viewport. Without `min-height: 0` flex children refuse to shrink
+    // below their content size, which is what produced the original
+    // "can't scroll to the ToC" bug on hub pages.
+    min-height: 0;
+    // brain: become a flex column ourselves so the inner <ol> can be
+    // flex-shrunk to whatever height the parent sidebar grants this
+    // section. Without this, the section flex-shrinks but the inner
+    // list keeps its hardcoded `max-height: 32vh` and renders past the
+    // section's box (overflow: visible) — visually spilling onto the
+    // Backlinks panel below it. Pairs with `min-height: 0` on the list.
+    display: flex;
+    flex-direction: column;
+
+    &[hidden] {
+      display: none;
+    }
+
+    > h3 {
+      margin-top: 0;
+      margin-bottom: 0.4rem;
+      font-weight: 600;
+      font-size: 0.7rem;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      color: var(--ink-1);
+    }
+  }
+
+  // brain: cap the related-docs list at ~one third of the viewport with
+  // its own internal scroll. The panel chrome (background, h3, padding)
+  // stays put; only the rows scroll. Combined with reordering the ToC
+  // above this panel in `quartz.layout.ts`, this guarantees the ToC and
+  // Backlinks panels remain reachable on hub pages with many related
+  // notes (COMPANY_REDACTED, COMPANY_REDACTED, etc. routinely pull 12+).
+  .brain-related-docs-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: grid;
+    gap: 0.35rem;
+    // brain: cap natural height at 32vh so a packed related set still
+    // leaves room for Backlinks below. `min-height: 0` plus the section
+    // being a flex column above lets the right sidebar's flex layout
+    // shrink the list (with its own internal scroll) when the column is
+    // squeezed — keeps the list inside the section's box instead of
+    // spilling onto the Backlinks panel below.
+    max-height: 32vh;
+    min-height: 0;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    scrollbar-width: thin;
+    scrollbar-color: var(--lightgray) transparent;
+
+    &::-webkit-scrollbar {
+      width: 4px;
+    }
+
+    &::-webkit-scrollbar-thumb {
+      background: var(--lightgray);
+      border-radius: 2px;
+    }
+  }
+
+  .brain-related-docs-item {
+    margin: 0;
+
+    > a {
+      display: grid;
+      grid-template-columns: 1.25rem minmax(0, 1fr);
+      gap: 0.45rem;
+      align-items: start;
+      padding: 0.35rem 0;
+      color: var(--ink-1);
+      text-decoration: none;
+      border-radius: 6px;
+      transition:
+        background var(--motion-fast) var(--motion-easing),
+        color var(--motion-fast) var(--motion-easing);
+
+      &:hover {
+        background: var(--accent-soft);
+        color: var(--ink-0);
+      }
+    }
+  }
+
+  .brain-related-docs-source {
+    width: 1.25rem;
+    line-height: 1.25;
+    text-align: center;
+    font-size: var(--fs-sm);
+  }
+
+  .brain-related-docs-body {
+    min-width: 0;
+    display: grid;
+    gap: 0.12rem;
+  }
+
+  .brain-related-docs-title {
+    color: var(--ink-0);
+    font-weight: 600;
+    font-size: var(--fs-sm);
+    line-height: 1.25;
+  }
+
+  .brain-related-docs-snippet {
+    display: -webkit-box;
+    color: var(--ink-2);
+    font-size: var(--fs-xs);
+    line-height: 1.35;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+
+  .brain-related-docs-empty {
+    margin: 0;
+    color: var(--ink-2);
+    font-size: var(--fs-xs);
+  }
+}