novahiz 0.1.0

package/bundled-skills/obsidian-cli/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: obsidian-cli
+description: Interact with Obsidian vaults using the Obsidian CLI to read, create, search, and manage notes, tasks, properties, and more. Also supports plugin and theme development with commands to reload plugins, run JavaScript, capture errors, take screenshots, and inspect the DOM. Use when the user asks to interact with their Obsidian vault, manage notes, search vault content, perform vault operations from the command line, or develop and debug Obsidian plugins and themes.
+---
+
+# Obsidian CLI
+
+Use the `obsidian` CLI to interact with a running Obsidian instance. Requires Obsidian to be open.
+
+## Command reference
+
+Run `obsidian help` to see all available commands. This is always up to date. Full docs: https://help.obsidian.md/cli
+
+## Syntax
+
+**Parameters** take a value with `=`. Quote values with spaces:
+
+```bash
+obsidian create name="My Note" content="Hello world"
+```
+
+**Flags** are boolean switches with no value:
+
+```bash
+obsidian create name="My Note" silent overwrite
+```
+
+For multiline content use `\n` for newline and `\t` for tab.
+
+## File targeting
+
+Many commands accept `file` or `path` to target a file. Without either, the active file is used.
+
+- `file=<name>` — resolves like a wikilink (name only, no path or extension needed)
+- `path=<path>` — exact path from vault root, e.g. `folder/note.md`
+
+## Vault targeting
+
+Commands target the most recently focused vault by default. Use `vault=<name>` as the first parameter to target a specific vault:
+
+```bash
+obsidian vault="My Vault" search query="test"
+```
+
+## Common patterns
+
+```bash
+obsidian read file="My Note"
+obsidian create name="New Note" content="# Hello" template="Template" silent
+obsidian append file="My Note" content="New line"
+obsidian search query="search term" limit=10
+obsidian daily:read
+obsidian daily:append content="- [ ] New task"
+obsidian property:set name="status" value="done" file="My Note"
+obsidian tasks daily todo
+obsidian tags sort=count counts
+obsidian backlinks file="My Note"
+```
+
+Use `--copy` on any command to copy output to clipboard. Use `silent` to prevent files from opening. Use `total` on list commands to get a count.
+
+## Plugin development
+
+### Develop/test cycle
+
+After making code changes to a plugin or theme, follow this workflow:
+
+1. **Reload** the plugin to pick up changes:
+   ```bash
+   obsidian plugin:reload id=my-plugin
+   ```
+2. **Check for errors** — if errors appear, fix and repeat from step 1:
+   ```bash
+   obsidian dev:errors
+   ```
+3. **Verify visually** with a screenshot or DOM inspection:
+   ```bash
+   obsidian dev:screenshot path=screenshot.png
+   obsidian dev:dom selector=".workspace-leaf" text
+   ```
+4. **Check console output** for warnings or unexpected logs:
+   ```bash
+   obsidian dev:console level=error
+   ```
+
+### Additional developer commands
+
+Run JavaScript in the app context:
+
+```bash
+obsidian eval code="app.vault.getFiles().length"
+```
+
+Inspect CSS values:
+
+```bash
+obsidian dev:css selector=".workspace-leaf" prop=background-color
+```
+
+Toggle mobile emulation:
+
+```bash
+obsidian dev:mobile on
+```
+
+Run `obsidian help` to see additional developer commands including CDP and debugger controls.

package/bundled-skills/obsidian-layout-adjustment/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: obsidian-layout-adjustment
+description: >
+  Workflow for working with the user on changing how Obsidian looks using CSS snippets.
+  Use this whenever the user asks to restyle Obsidian, tune a vault's visual layout,
+  adjust tabs, sidebars, note surfaces, properties, backlinks, graph panes, file
+  explorer rows, icons, links, shadows, active states, or CSS snippets. Also use
+  it when the user says a visual CSS change did nothing, still looks wrapped, is not
+  lifted, is unreadable, or needs to be refactored without changing the current
+  appearance.
+---
+
+# Obsidian Layout Adjustment
+
+This skill is for changing how Obsidian looks with CSS files while working with the user's visual language.
+
+Obsidian is always the same kind of environment: app frame, tab headers, side docks, view headers, pane shells, note surface, properties, file explorer, backlinks, graph, rendered markdown, and status bar. The vault, theme, snippets, plugins, and desired taste direction change, but the canvas stays Obsidian.
+
+The core behavior is translation:
+
+> the user names a visible Obsidian object. Translate that phrase into the stable Obsidian layer/backend object, edit the active snippets safely, screenshot the result, and keep iterating without losing good states.
+
+This is not a general CSS workflow and not a fixed-theme generator.
+
+## Normal Output Mode
+
+This skill should make live styling work faster, not turn every small request into a report.
+
+In normal use:
+
+1. Say the mapping only when it prevents ambiguity.
+2. Keep the mapping short: one sentence is usually enough.
+3. Then act: inspect active snippets, checkpoint, patch, format, reload, screenshot.
+4. Report the result concisely with changed files, checkpoint, and screenshot status.
+
+Good normal update:
+
+> "I’m treating 'tabs above the note' as workspace tab headers, not the arrows/book/dots view header. I’ll checkpoint active snippets, patch that selector family only, and screenshot the tab strip."
+
+Do not write a long workflow report unless:
+
+- the user asks for a plan, audit, review, or explanation.
+- You are running evals or building this skill.
+- You are refactoring without visual changes.
+- The request is ambiguous enough that acting first would be risky.
+
+The value is in preventing bad CSS loops while still moving quickly.
+
+## Use The Reference
+
+Read `references/workflow-reference.md` when:
+
+- the user names a visible Obsidian object in natural language.
+- The requested target could be more than one Obsidian layer.
+- A screenshot shows "nothing changed," "still wrapped," "not lifted," uneven edges, washed-out surfaces, or unreadable icons.
+- You are refactoring active snippets without changing the accepted look.
+- You need the Obsidian surface map, change-type map, or failure-pattern list.
+
+The reference is Obsidian-specific. Use it before treating the UI as an unknown web page.
+
+## Operating Loop
+
+1. Start from the live vault.
+2. Read `<vault>/.obsidian/appearance.json`.
+3. Treat `enabledCssSnippets` as the active styling source of truth.
+4. Read active snippets before archives, backups, or old experiments.
+5. Translate the user's phrase into an Obsidian object and owning layer.
+6. Classify the change type: color, readability, lift, shape, structure, density, simplification, workflow, or refactor.
+7. Save a named checkpoint before subjective edits: copy the active snippets to `.obsidian/snippet-archive/`, never into `.obsidian/snippets`, so the snippet picker stays clean.
+8. Re-read the exact current block, then edit one owning layer: stage, shell, header, wrapper, or child. Formatting reshapes the file; a patch written from a remembered shape misses mechanically.
+9. Format CSS.
+10. Reload/focus Obsidian and screenshot the exact affected area.
+11. Use the screenshot and the user's correction as evidence.
+12. If it fails, inspect ownership or restore; do not keep piling CSS onto the same wrong target.
+13. Refactor only after the user accepts the visual state.
+
+## Translate Before Editing
+
+The user will usually name what they see, not the selector:
+
+- "tabs above the note"
+- "arrows/book/dots above the note"
+- "left side note buttons"
+- "right sidebar"
+- "links in those little areas"
+- "the thing around the note"
+- "selected icon"
+- "top-left white corner"
+
+Before editing, map the phrase:
+
+```text
+user phrase -> visible object -> Obsidian layer -> likely selector/settings surface -> change type -> owning layer
+```
+
+Say the mapping back when it could be ambiguous:
+
+> "When you say the tabs above the note, I am treating that as the workspace tab headers, not the arrows/book/dots row inside the note pane."
+
+This is the main mistake-prevention step. Most frustrating failures came from changing a plausible element that was not the object the user meant, or changing a child when the wrapper/header/stage owned the visible shape.
+
+## Stable Layer Stack
+
+Use this compact map first, then verify exact selectors in the live vault:
+
+| the user points at | Usually means |
+| --- | --- |
+| top-left white/native area | titlebar/native chrome or adjacent app header |
+| tabs above note | workspace tab headers |
+| plus next to tab | new tab control |
+| green/top bar | app frame or tab header container |
+| far-left icons | ribbon / side dock |
+| selected side icon | active side-dock tab header plus icon state |
+| buttons above file list | file explorer nav controls |
+| left note/folder buttons | file explorer tree rows |
+| vault name/footer | side dock profile/footer |
+| arrows/book/dots above note | markdown view header |
+| note/page/paper | markdown leaf, editor, or readable surface |
+| note shadow/lift/edge | stage, shell, gutter, overflow, or pseudo-element relationship |
+| properties | metadata container or Properties View workflow |
+| links | internal link spans in reading/editing modes |
+| right sidebar | right workspace split and utility leaves |
+| linked mentions/backlinks | backlinks plugin result groups |
+| graph | graph plugin leaf/canvas |
+| bottom stats | status bar |
+
+The visible object and backend layer should be treated as stable across Obsidian work. Exact class names can vary by theme/plugin/app version, so verify in the live vault before patching.
+
+## Change-Type Split
+
+The same object needs different work depending on the request:
+
+- **Color/accent**: update background, text, border, icon stroke/fill, and active/hover/focus states together.
+- **Readability**: check rendered contrast, especially for icons on colored toolbars.
+- **Lift/depth**: decide foreground, stage, shell, gutter, overflow, and exterior shadow. Lift is a relationship, not just `box-shadow`.
+- **Rounded corners**: check parent shell, child radius, overflow, and adjacent background.
+- **Structure**: style the wrapper/header/shell that owns the visible shape.
+- **Simplification**: remove wrappers, borders, gradients, shadows, or pseudo-elements before adding more treatment.
+- **Properties/workflow**: consider Obsidian's Properties View or display settings before CSS-compressing metadata.
+- **Refactor**: preserve cascade order and verify the screenshot does not change.
+
+If a target needs two change types, do two passes. For example, make side-dock icons readable first, then tune the selected-state color.
+
+## What To Change First
+
+Start with:
+
+- active CSS snippets from `appearance.json`
+- Obsidian settings when the issue is a workspace behavior
+- Style Settings or theme variables when the change should remain tunable
+- stable Obsidian wrappers: tab headers, view headers, pane shells, side docks, file rows, note surface, backlinks groups
+
+Avoid changing first:
+
+- Obsidian app bundle files
+- community plugin source files
+- installed theme source files
+- vault content just to force visual styling
+- app internals/minified code before active snippets and theme CSS are ruled out
+
+Ask for explicit confirmation before:
+
+- switching themes
+- disabling snippets or plugins
+- hiding/moving properties as a workflow change
+- changing global typography or editor density substantially
+- deleting archived experiments
+- changing files outside `.obsidian/snippets` or Obsidian settings
+
+## Screenshot Gate
+
+CSS validity is not visual success. The screenshot is product truth.
+
+For every meaningful visual pass:
+
+1. Save checkpoint.
+2. Patch.
+3. Format CSS.
+4. Reload or focus Obsidian.
+5. Screenshot the affected area.
+6. Compare the screenshot to the complaint.
+
+If another window covers Obsidian, retake the screenshot. Verify the verifier: confirm Obsidian is actually frontmost before trusting a capture (AppleScript can check the frontmost process). If the issue is tiny, capture just that region — `screencapture -R<x,y,w,h> out.png` — around the edge, icon, tab, row, or pane.
+
+If the screenshot disproves the fix, keep working, restore, or say it failed. Do not close as if formatting proved success.
+
+## Failure Signals
+
+the user's corrections are selector evidence:
+
+- "nothing changed" means wrong selector, wrong layer, clipping, coverage, or override.
+- "still wrapped" usually means both wrapper and child are styled.
+- "not lifted" means the stage/shell/gutter relationship is wrong or too subtle.
+- "right side got lighter" points to an overlay or pseudo-element on top of the note.
+- "icon is impossible to see" means active/inactive button fill and icon color must be handled together.
+- "overdone" often means remove treatment before adding another one.
+
+If a direction fails twice, restore the last good checkpoint and change the ownership model.
+
+## Refactor Rule
+
+Do not refactor during taste exploration.
+
+When the user likes the look:
+
+1. Save a baseline checkpoint.
+2. Add or update a file map and section headers.
+3. Preserve selector order unless changing it intentionally.
+4. Format CSS.
+5. Check the diff for accidental visual changes.
+6. Screenshot Obsidian.
+7. Archive inactive iterations outside `.obsidian/snippets`.
+
+CSS size is usually less dangerous than cascade confusion and a messy active snippet picker.
+
+## Closing Report
+
+When done, keep the closeout short. Report:
+
+- active snippet files changed
+- checkpoint paths saved
+- what user phrase mapped to which Obsidian layer
+- what was screenshot-verified
+- anything not verified or intentionally deferred
+
+Avoid explaining the whole workflow after every small pass. The workflow should be visible in the actions: checkpoint, scoped edit, screenshot, and evidence-based next step.

package/bundled-skills/obsidian-layout-adjustment/evals/evals.json

@@ -0,0 +1,53 @@
+{
+  "skill_name": "obsidian-layout-adjustment",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "My Obsidian vault is at ~/Documents/Window/SummerHustle. The right sidebar should feel more like the left side, but the side icons are hard to read and the backlink cards look overwrapped. Make one visual pass, preserve the current look first, and verify it with a screenshot.",
+      "expected_output": "The agent reads appearance.json, identifies active snippets, checkpoints them outside .obsidian/snippets, maps 'right sidebar' to the right utility split/backlink pane and 'side icons' to side-dock tab headers, styles the owning shell or wrapper rather than nesting card treatments, formats CSS, screenshot-checks the affected pane, and reports files/checkpoints.",
+      "expectations": [
+        "Reads the vault's .obsidian/appearance.json and treats enabledCssSnippets as the active source of truth.",
+        "Maps 'right sidebar' to the right workspace utility split/backlinks pane and maps 'side icons' to side-dock tab headers or icon button states.",
+        "Chooses the visible wrapper/shell as the likely owner for the overwrapped backlink/card treatment instead of adding nested styling to inner text.",
+        "Includes a named checkpoint plan outside .obsidian/snippets before any subjective visual pass.",
+        "Includes screenshot verification of the affected right pane and icon states before claiming success."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "The note is supposed to look lifted, but the shadow keeps doing nothing. Don't keep guessing. Figure out why it isn't visible and make the smallest safe fix.",
+      "expected_output": "The agent treats 'nothing changed' as an ownership or clipping failure, maps note lift to stage/shell/gutter rather than only the note child, checkpoints active snippets, avoids app internals first, makes one scoped fix, crops or inspects the note edge in a screenshot, and restores or changes ownership if the visual evidence fails.",
+      "expectations": [
+        "Treats repeated 'nothing changed' as evidence of wrong selector ownership, clipping, coverage, or override rather than continuing to guess.",
+        "Maps note lift to a relationship among stage, pane shell, note surface, gutters, overflow, and pseudo-elements rather than only applying box-shadow to markdown content.",
+        "Avoids editing Obsidian app bundle, theme internals, or plugin internals before ruling out active snippet CSS.",
+        "Proposes one smallest safe fix and a rollback path from the last good checkpoint.",
+        "Requires a screenshot or crop of the note edge/shadow area before declaring the lift fixed."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "The tabs above the note need more contrast, and the plus is impossible to see. The row with the arrows/book/dots is fine. Update the right thing.",
+      "expected_output": "The agent distinguishes workspace tab headers from markdown view headers, maps the plus to the new tab control, handles active/inactive tab and icon contrast states, checkpoints active snippets, makes a focused tab-header change, and screenshot-verifies without changing the view header.",
+      "expectations": [
+        "Explicitly distinguishes workspace tab headers from the markdown view header row that contains arrows, book, and dots.",
+        "Maps the plus to the new tab control in the workspace tab/header area.",
+        "Handles active, inactive, hover, and icon contrast states together instead of changing only a background color.",
+        "Scopes the change to tab/header selectors and avoids changing the arrows/book/dots view header.",
+        "Includes a screenshot check that verifies both contrast and that the untouched row stayed unchanged."
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "We have a bunch of old Obsidian CSS experiments and the active snippet is getting hard to understand. Refactor it without changing the current visual design.",
+      "expected_output": "The agent reads appearance.json, separates active snippets from archived iterations, saves a baseline checkpoint, preserves selector order, adds a file map and section headers, formats CSS, checks the diff for unintended visual changes, screenshot-verifies the same look, and does not delete experiments in the same pass unless explicitly asked.",
+      "expectations": [
+        "Reads appearance.json first and separates active snippets from archived or inactive iterations.",
+        "Saves a baseline checkpoint before refactoring and keeps archives outside .obsidian/snippets so the snippet picker stays clean.",
+        "Preserves selector order and cascade behavior unless a screenshot-verified reason requires changing it.",
+        "Adds or improves a file map and section headers without turning the active CSS into a large narrative document.",
+        "Runs formatting/diff checks and screenshot-verifies that the visual design did not change."
+      ]
+    }
+  ]
+}

package/bundled-skills/obsidian-layout-adjustment/references/workflow-reference.md

@@ -0,0 +1,212 @@
+# Obsidian Layout Workflow Reference
+
+Use this reference when working with the user on changing how Obsidian looks using CSS snippets.
+
+This file is intentionally Obsidian-specific. The design direction can change, but the canvas stays Obsidian: app frame, tab headers, side docks, view headers, pane shells, note surface, metadata, rendered markdown, file explorer, utility panes, graph, and status bar.
+
+## User Language To Obsidian Backend
+
+the user names the visible object. Translate it into the Obsidian object before editing.
+
+For live styling work, this translation should usually be brief and operational:
+
+> "I’m treating 'right sidebar' as the right workspace split/backlinks pane, and 'side icons' as side-dock tab/header icon states."
+
+Then inspect, checkpoint, patch, format, reload, and screenshot. Long translation tables belong in evals, audits, or planning notes, not in every small visual pass.
+
+| the user might say | Usually means | Backend / selector family to inspect |
+| --- | --- | --- |
+| tabs above the note | open workspace tab headers | `.workspace-tab-header-container`, `.workspace-tab-header`, `.workspace-tab-header-inner` |
+| plus next to the tab | new tab button in tab strip | `.workspace-tab-header-new-tab`, tab header `.clickable-icon` |
+| green bar / top bar / row across top | app frame or workspace tab header strip | `.workspace-tab-header-container`, titlebar variables |
+| top-left corner is white | native titlebar area or neighboring app row | `--titlebar-background`, `--titlebar-background-focused`, adjacent tab header container |
+| icons on far left | ribbon / side dock | `.workspace-ribbon`, `.side-dock-ribbon`, `.workspace-ribbon.mod-left` |
+| selected icon | active side-dock tab header, not only the SVG | side-dock `.workspace-tab-header.is-active`, nested icon |
+| secondary icons | view action buttons in pane headers | `.view-actions .clickable-icon`, `.view-header .clickable-icon` |
+| buttons above the file list | file explorer nav buttons | `.nav-buttons-container`, `.nav-action-button`, `.clickable-icon` |
+| left side note buttons | file explorer note/folder rows | `.nav-file-title`, `.nav-folder-title`, `.tree-item-self` |
+| folder/note color | explicit file explorer row mapping or fallback | `data-path` selectors, track variables |
+| bottom vault name | vault switcher / left footer | `.workspace-sidedock-vault-profile` |
+| arrows/book/dots above the note | markdown view header | `.view-header`, `.view-header-nav-buttons`, `.view-actions` |
+| stripe below the header | view header, markdown body layer, or pseudo-element | `.view-header`, markdown leaf, `::before` / `::after` |
+| the note / page / paper | markdown pane or readable/editor surface | markdown leaf, preview sizer, editor content container |
+| note shadow / right edge | stage, shell, gutter, or parent clipping | workspace split, markdown shell, pseudo-elements, overflow |
+| right side got lighter | overlay or pseudo-element over note surface | markdown pane `::before` / `::after`, gradients |
+| properties at the top | metadata container or Properties View | `.metadata-container`, `.metadata-properties`, Properties plugin/settings |
+| right sidebar | right utility split | `.workspace-split.mod-right-split`, right pane leaves |
+| backlinks pane / linked mentions | backlink plugin content and groups | backlink pane, search result wrappers |
+| links to other pages | internal links in reading/editing modes | `.internal-link`, `.cm-hmd-internal-link`, unresolved link selectors |
+| graph view | graph plugin pane/canvas | `.workspace-leaf-content[data-type='graph']`, graph canvas/container |
+| bottom stats | status bar | `.status-bar`, status bar items |
+
+If the phrase could mean more than one layer, say the mapping back before editing.
+
+## Stable Obsidian Surface Map
+
+| Visible area | Obsidian layer | What can usually be changed | Caution |
+| --- | --- | --- | --- |
+| native/titlebar area | native/window chrome and titlebar-adjacent app row | exposed titlebar variables, adjacent row color | native chrome may not be fully reachable |
+| top strip with open note tabs | workspace tab header layer | active/inactive tab shape, background, text, close icon, plus button, spacing | different from markdown view header |
+| left vertical icon rail | ribbon / side dock | rail background, icon button shape, active/inactive states, icon contrast | active state needs fill and icon color |
+| file explorer action buttons | file explorer nav controls | icon buttons, spacing, selected/hover states | should not fight file rows |
+| file/folder list | file explorer tree | row shape, explicit color mapping, fallback color, selected/hover state, density | avoid accidental meaning from positional cycling |
+| vault name/footer | side dock footer/profile | background, text/icon contrast, spacing | should belong to side rail/frame |
+| arrows/book/dots row | markdown view header | shelf color, icon readability, border/stripe removal | "header" may mean tab header or view header |
+| note/page/paper | markdown leaf and readable/editor surface | paper color, width, padding, rounded corners, editor/reader parity | lift belongs to shell/stage relationship |
+| note edge/shadow/lift | stage, pane shell, split gutter | background, spacing, exterior shadow, overflow/gutter | too much gutter becomes a slab |
+| properties block | metadata/properties layer | compacting, card treatment, muted labels, or moving workflow to Properties View | often a setting/workflow question |
+| rendered markdown | headings, links, callouts, lists, code, embeds | semantic styling | persistent surfaces should carry identity first |
+| internal links | rendered and editor link spans | color, underline, background, editor/reader parity | links are high-value objects |
+| right utility panes | right workspace split and utility leaves | pane shell, header shelf, group spacing, background, icon states | utility panes usually need less treatment |
+| backlinks/search results | plugin result tree | group wrappers, excerpt rows, match highlights, link color | avoid wrapper plus child card treatment |
+| graph view | graph plugin leaf/canvas | pane shell, background, reachable graph colors | canvas internals may be limited |
+| status bar | bottom app status layer | background, text/icon color, spacing | should belong to app frame language |
+| Style Settings/theme variables | theme control layer | global colors, density, typography, radius, plugin-exposed controls | use when future tuning matters |
+
+## Change-Type Map
+
+The same visible object can require different backend work depending on what the user asks for.
+
+### Color or accent
+
+Usually adjust background, text color, border color, icon stroke/fill, active state, hover state, focused state, and muted/disabled state together.
+
+Failure pattern: changing only the background makes icons or text unreadable.
+
+### Readability
+
+Usually adjust rendered contrast, button background and icon color together, selected/unselected states, hover/focus states, and muted text.
+
+Failure pattern: a subtle top border or theoretically nice palette fails in the actual toolbar.
+
+### Lift or depth
+
+Usually adjust stage color, shell spacing, parent overflow, exposed gutter, exterior shadow, and pseudo-elements only when they sit outside the content surface.
+
+Failure pattern: adding more shadow does nothing because it is behind the object, clipped, or covered. Interior highlights can wash out the note.
+
+### Rounded corners
+
+Usually adjust parent shell radius, child radius, overflow behavior, and adjacent surface color.
+
+Failure pattern: the inner child becomes rounded but the parent still clips square.
+
+### Structure
+
+Usually adjust pane shell, wrapper, header shelf, or group container.
+
+Failure pattern: bordering an inner element makes the UI look double-wrapped.
+
+### Simplification
+
+Usually remove borders, wrappers, gradients, shadows, pseudo-elements, or nested card styling.
+
+Failure pattern: adding more treatment makes an already overdone area worse.
+
+### Properties and metadata
+
+First consider Obsidian's built-in Properties View, display settings, or sidebar workflow. Use CSS compacting after deciding the workflow.
+
+Failure pattern: treating properties as only a CSS block ignores that the object may belong somewhere else.
+
+### Refactor
+
+Save a baseline, preserve selector order, add section headers/file map, format, screenshot, and archive inactive experiments outside `.obsidian/snippets`.
+
+Failure pattern: reordering or deleting during refactor changes the look.
+
+## Ownership Model
+
+Pick the object that owns the visible shape:
+
+- **Stage**: background an object lifts off from.
+- **Shell**: pane, note surface, or card container.
+- **Header**: tab strip, view toolbar, or pane shelf.
+- **Wrapper**: repeated group such as file row or backlink group.
+- **Child**: text, icon, link, match span, or excerpt.
+
+Prefer the highest layer that owns the visible object. If both wrapper and child are styled, the UI often looks double-wrapped.
+
+## Specific Mistake Patterns
+
+Because Obsidian's layer map is stable, the mistakes can be specific:
+
+- Confusing workspace tab headers with markdown view headers.
+- Styling a result row when the backlink group wrapper owns the shape.
+- Trying to create note lift from inside the note surface instead of the stage/gutter.
+- Treating side-dock icon color as only SVG color instead of active tab state plus icon contrast.
+- Changing child radius while the parent shell still clips square.
+- Assuming native titlebar area can always be styled directly.
+- Treating properties as only a CSS block instead of a possible workspace/sidebar workflow.
+- Chasing app internals before ruling out active snippets.
+- Patching from a remembered file shape after the formatter reshaped it, so the edit misses mechanically.
+
+## Failure Signals
+
+the user's corrections are diagnostic:
+
+- **"Nothing changed"**: wrong selector, wrong layer, clipping, coverage, override, or not reloaded.
+- **"Still wrapped"**: wrapper and child both styled; pick one.
+- **"Not lifted"**: wrong stage/shell/gutter model, clipped shadow, insufficient surface contrast, or overly subtle effect.
+- **"Right side got lighter"**: overlay or pseudo-element sits over the content surface.
+- **"Icon is impossible to see"**: active/inactive fill and icon color must be tested together.
+- **"Overdone"**: remove treatment before adding another.
+- **"Wrong side"**: mapping was not restated; stop and remap.
+
+If the same failure repeats twice, restore the last good checkpoint and change the ownership model.
+
+## Breakthrough Concepts
+
+- The screenshot is product truth.
+- the user's corrections are selector evidence.
+- Obsidian is layered furniture, not a flat page.
+- The owning wrapper matters more than the prettiest selector.
+- Lift is a relationship, not a shadow.
+- Accent works when it becomes architecture.
+- Navigation can carry mental model.
+- Refactor only after the look lands.
+
+## Snippet Organization
+
+For a mature active snippet, prefer sections like:
+
+1. Design tokens and Style Settings controls.
+2. Theme/app variables.
+3. App frame and titlebar.
+4. Workspace panes and gutters.
+5. Tabs and side-dock controls.
+6. Main note/editor surface.
+7. Properties and metadata.
+8. Left explorer.
+9. Right utility panes.
+10. Rendered markdown objects.
+11. Track or note/folder mappings.
+12. Utilities and compatibility overrides.
+
+Keep experiments outside `.obsidian/snippets` so the snippet picker stays clean. Active snippets should be the live design, not the archive.
+
+## What Usually Should Not Be Changed First
+
+Avoid these as first moves:
+
+- Obsidian app bundle files.
+- Community plugin source files.
+- Installed theme source files.
+- Vault content just to force visual styling.
+- Large typography changes bundled with unrelated layout changes.
+- Rare markdown components used as the main identity system.
+- App internals/minified code before active snippets and theme CSS are ruled out.
+- Broad snippet rewrites before a stable visual state exists.
+- Deleting old experiments before the accepted look is checkpointed.
+
+## Explicit Confirmation Zone
+
+Ask before:
+
+- switching themes
+- disabling snippets or plugins
+- hiding or moving properties/metadata as a workflow change
+- changing global typography or editor density substantially
+- changing file/folder color logic from explicit mapping to automatic cycling
+- deleting or archive-cleaning old snippet iterations
+- changing anything outside `.obsidian/snippets` or Obsidian settings files