# blip-rules — INDEX

The canonical home for jetblip dev/coding/architecture/workflow rules.
Browse at https://infra.jetblip.com/blip-rules/INDEX.md.

## Session start

1. **Always** load this INDEX first.
2. Scan the categories below.
3. Load only the category files that match the task you've been asked
   to do. Don't load everything.
4. If a rule you need isn't here, add it — to the right category file
   AND extend INDEX if the category itself is new.

## Two-folder mindset (read this once, internalise it)

Two folders, two purposes, **no duplication**:

- **`architecture/`** — *how the feature is built **today***. Slim
  operational docs. Where to edit when something changes. Always
  current. **Does NOT contain alternatives lists.**
- **`decisions/`** — *why we chose the current shape, and what
  alternatives we passed on*. Atomic dated ADRs. Immutable. Each one
  is one decision; if you change your mind, write a new ADR that
  supersedes the old one. See [`decisions/INDEX.md`](decisions/INDEX.md)
  for the heuristic on when an ADR is worth writing.

When you reach for an architecture doc, the ADR links at the top of
it tell you which decisions backed the current design. When you
reach for an ADR, the Implementation section tells you which
architecture doc / file owns the current realisation.

Trivial decisions (renames, CSS tweaks, mechanical refactors, forced
external bumps) skip the ADR layer and live in commit messages
only.

## Categories

| Path | When to load |
|---|---|
| `architecture/sheets.md` | Anything touching the main drawer, More sheet, Customize sheet, handle pill, header layout, sheet sizing, stacking, sheet-to-body z-index. |
| `architecture/ids-and-tooltips.md` | Adding/renaming interactive elements. `bj-*` id format. Glossary at `/blipjot-ids.json`. Tooltip runtime. |
| `architecture/production-modules.md` | Moving a feature from mockup to production. Standalone modules under `widget/shared/`, bj-* ids from day one, integration with legacy jjt-drawer until Tier 2.B. |
| `architecture/scan-result-integration.md` | Wiring the post-scan result panel into `/blip-scan/scanner`. Slim operational guide; alternatives + reasoning live in the linked ADRs at the top of the doc. |
| `decisions/INDEX.md` | The ADR index. Chronological list + by-feature index + by-topic cross-cutting patterns + the "when do I write an ADR vs not?" heuristic. Read this before opening any individual ADR. |
| `css/patterns.md` | Writing CSS for jetblip mockups or production. The "do this" list. |
| `css/antipatterns.md` | The "don't do this" list — patch-on-patch, `!important` wars, `contain: layout paint` clipping, `::before` on flex children, off-screen `offsetHeight` reads. |
| `javascript/event-handling.md` | Click/mousedown/focus/blur ordering, event delegation, bubbling, browser-specific timing (Chrome on Windows is the primary target). |
| `javascript/search-toggle.md` | The search 🔍 ↔ red ✕ toggle. Every trap we hit from v30–v38 (focusout race, log-probe lie, sheet-scoped filter). |
| `workflow/deploy-checklist.md` | What to update on every mockup deploy — manifest, ids glossary, mockup index. Always-visual-verify rule. |
| `workflow/efficiency.md` | Stop patching after 3 failures. Always verify in Chrome on Windows. Test before reporting done. |
| `workflow/test-on-both-pc-and-mobile.md` | Every UI change tests in desktop AND mobile (DevTools device toolbar) before reporting done. Reliable mobile detection patterns. |
| `workflow/ci-cd-mandatory.md` | Every production-deploying repo MUST have GitHub Actions. Manual SSH/cp/reload is forbidden once Actions is configured. Standard secrets matrix + Pi-behind-CF-tunnel options. |
| `workflow/live-route-verification.md` | Never report a route as live until you've fetched it and got HTTP 200. Three layers to check: Flask route + `_PUBLIC_ENDPOINTS` whitelist + nginx `location` block. Verification sequence + common 404 causes after "successful" deploy. |
| `mockups/standards.md` | Canonical BLIPJOT MOCKUP STANDARDS list — filename CalVer, mobile-first, mockup index link, debug gear, glossary-driven tooltips, shared `renderSheetHeader()`, manifest-driven index. |

## Common workflows → files to load

| Task | Load |
|---|---|
| "Fix a bug in the search toggle / search filter" | `javascript/search-toggle.md`, `javascript/event-handling.md`, `architecture/sheets.md` |
| "Change the look of a sheet header" | `architecture/sheets.md`, `css/patterns.md`, `css/antipatterns.md` |
| "Add a new interactive element to a mockup" | `architecture/ids-and-tooltips.md`, `mockups/standards.md` |
| "Ship a new mockup version" | `mockups/standards.md`, `workflow/deploy-checklist.md` |
| "Refactor or rewrite a component" | `workflow/efficiency.md` (the 3-strike rule), then the architecture file for the component |
| "Move a feature from mockup to production" | `architecture/production-modules.md`, then the relevant feature's architecture file |
| "Change post-scan UX in /blip-scan/scanner" | `architecture/scan-result-integration.md` |
| "Investigate a Chrome-only or browser-specific bug" | `javascript/event-handling.md`, `workflow/efficiency.md` |
| "Anything that ships UI to a real user" | `workflow/test-on-both-pc-and-mobile.md` (the dual-viewport test matrix) |
| "Setting up deploy for a new repo / fixing a manual-deploy pattern" | `workflow/ci-cd-mandatory.md` |
| "Adding a new public route / debugging 404 after deploy" | `workflow/live-route-verification.md` |
| "Why is feature X built this way?" | `decisions/INDEX.md` — find the relevant ADR(s) by feature or topic |
| "I want to swap in a rejected alternative for feature X" | `decisions/INDEX.md` — find the ADR, read its "How to revisit" section, write a new ADR superseding it |
| "I'm about to make a non-trivial design choice" | `decisions/INDEX.md` — write an ADR before committing the code (or alongside it in the same PR) |
| Anything else | Start here, scan, pick. |

## Architecture meta-rules

These apply to the rules system itself:

- **One source of truth per topic.** If a rule lives in two files, pick one and link from the other.
- **Alternatives live in ADRs only.** `architecture/*` docs describe the current shape, not the menu of options. If you find yourself listing alternatives in an architecture doc, that material belongs in an ADR — extract it.
- **ADRs are immutable.** Never edit an ADR's body after it's accepted. If reality changes, write a new ADR that supersedes the old one.
- **Cite cases.** When a rule comes from a specific bug, name the version
  it appeared in (e.g. "v30–v37 search reopen flicker"). Future readers
  can read the commit history to understand the why.
- **Rules drift fast.** When a rule is contradicted in practice, fix
  the rule (or delete it). Don't leave stale rules sitting around.
- **Add to glossary first.** New `bj-*` id? Add to `/blipjot-ids.json`
  first, then to the HTML.
- **Visual verification > console logs.** Logs can lie (and have —
  see `javascript/search-toggle.md` Bug A from v33–v38).

## Where things are not

- **Operator-personal** plans, infra recipes, brand decisions, and
  per-session knowledge live in the `blip-rules` repo on disk
  (`D:/jetblip/github/blip-rules/`). That repo's README points back
  here for the dev-rule content.
- **Public mockup index** at https://infra.jetblip.com/blipjot-mockups
  (driven by `/blipjot-manifest.json`).
- **Tooltip glossary** at https://infra.jetblip.com/blipjot-ids.json.