@monoes/monomindcli 1.8.0 → 1.9.0

package/.claude/skills/monodesign/reference/ux-research.md

@@ -0,0 +1,143 @@
+# UX Research
+
+Validate design decisions with evidence. Research before redesigning; test before shipping.
+
+## When to Research
+
+| Signal | Method |
+|---|---|
+| "We don't know if users want this" | User interviews (5–8 participants) |
+| "We don't know if users can do this" | Usability testing (5 tasks, think-aloud) |
+| "We don't know which version is better" | A/B testing (statistical significance required) |
+| "We don't know who our users are" | Survey + analytics segmentation |
+| "We're redesigning a live product" | Contextual inquiry + session recording analysis |
+
+## Study Plan
+
+Before any research session:
+
+```markdown
+## Research Plan: [Feature/Product Name]
+
+**Research question**: [One clear question this study answers]
+**Method**: [Interview / Usability test / Survey / A/B test]
+**Participants**: [N=X; criteria: role, experience, age range; how recruited]
+**Timeline**: [Dates for recruiting, sessions, synthesis, readout]
+**Success**: [What finding would change a product decision]
+
+### Session protocol
+- [Task 1]: [Goal — what we want to observe, not prescribe]
+- [Task 2]: ...
+- Post-task questions: "How difficult was that? Why?"
+- Closing: "What surprised you? What would you change?"
+```
+
+## User Persona Template
+
+Personas are empirical — built from interview synthesis, not imagination. A persona without a source citation is a fiction.
+
+```markdown
+## [Persona Name] — [One-line description]
+
+**Source**: [N interviews + X survey responses, Month Year]
+
+### Context
+- Role: [job title, team size, seniority]
+- Environment: [device, OS, when/where they use the product]
+- Technical fluency: [1–5 scale with evidence]
+
+### Goals
+Primary: [What they're actually trying to accomplish]
+Secondary: [Nice-to-have outcomes]
+
+### Frustrations (direct quotes where possible)
+- "[Their words]" — quote from interview participant
+- [Observed behavior that contradicts stated preference]
+
+### Mental model
+[How they currently think about the problem domain — diagram if useful]
+
+### Decision triggers
+[What causes them to start using, stop using, recommend, or abandon]
+```
+
+## Usability Test Protocol
+
+5 participants reveals 85% of usability issues (Nielsen's rule). Run moderated think-aloud tests before major launches.
+
+```markdown
+## Usability Test: [Feature Name]
+
+**Prototype/build**: [URL or Figma link]
+**Tasks** (state goal, not steps):
+1. "Find a plan that fits your budget" ← correct
+   "Click Pricing, then select Pro" ← wrong (leads the user)
+2. ...
+
+**Observation sheet** (one per participant):
+| Task | Completed? | Time | Errors | Quotes / Observations |
+|------|-----------|------|--------|----------------------|
+| T1   |           |      |        |                      |
+
+**Severity scale**:
+- P0: Blocks task completion — fix before launch
+- P1: Causes errors or frustration — fix this sprint
+- P2: Causes hesitation — fix next sprint
+- P3: Polish issue — backlog
+```
+
+## Synthesis
+
+After 5+ sessions, synthesize before drawing conclusions. Affinity mapping is the default method.
+
+Steps:
+1. Transcribe or note-take immediately after each session
+2. Write observations on individual cards ("User tried X before Y")
+3. Group cards by theme across participants
+4. Count frequency: "4/5 users misread the CTA as navigation"
+5. Map to product decisions: what changes, what validates current design
+
+**Red flags that invalidate a finding:**
+- Only one participant showed this behavior
+- Observation conflicts with analytics data — investigate before concluding
+- "Users said they would do X" (stated preference ≠ behavior)
+
+## A/B Testing Standards
+
+Don't A/B test unless:
+- You have enough traffic for statistical significance (use a calculator — typically n=1,000+ per variant)
+- The test runs ≥2 weeks to account for weekly cycles
+- You have a pre-registered hypothesis ("Changing CTA copy will increase conversion by 10%")
+- You have a single primary metric per test
+
+**What to test**: CTAs, headlines, onboarding steps, form field count, pricing page layout.  
+**What not to test**: Navigation structure, brand identity, accessibility requirements.
+
+## Research Repository
+
+After each study, file a one-page summary:
+
+```markdown
+## Research Summary: [Study Name] — [Date]
+
+**Question**: [What we set out to learn]
+**Method + participants**: [Brief]
+**Top 3 findings**:
+1. [Finding with evidence — quote or count]
+2. ...
+3. ...
+**Recommended changes** (linked to findings):
+- Design: [What to change]
+- Product: [What to consider]
+**Follow-up questions this surfaced**: [What to research next]
+```
+
+Store in `docs/research/` or equivalent. Link from design decisions so future teammates understand why choices were made.
+
+## Inclusive Research
+
+- Recruit participants with disabilities in every study (not just accessibility-specific studies)
+- Test on real devices users own — not just latest iPhone/MacBook
+- Account for non-native language users if the product has international reach
+- Analyze session recordings for accessibility errors: keyboard traps, screen reader failures, zoom breakage
+- Don't use "average user" — disaggregate findings by user segment

package/.claude/skills/monodesign/reference/ux-rules.md

@@ -0,0 +1,211 @@
+# UX Rules — Implementation-Level Guidance
+
+170+ rules across 10 categories, ordered by priority. Use during `audit`, `critique`, and `review` workflows to catch implementation-level issues that antipattern detection misses.
+
+---
+
+## Priority 1: Accessibility (CRITICAL)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `color-contrast` | Minimum 4.5:1 for normal text; 3:1 for large text (18px+ or 14px+ bold) | WCAG AA |
+| `focus-states` | Visible focus rings on all interactive elements (2–4px outline) | Never remove outlines |
+| `alt-text` | Descriptive alt text for all meaningful images; `alt=""` for decorative | |
+| `aria-labels` | aria-label for icon-only buttons; all interactive elements labeled | |
+| `keyboard-nav` | Tab order matches visual order; all actions reachable without a mouse | |
+| `form-labels` | `<label for="">` wired to every input; no placeholder-as-label | |
+| `skip-links` | "Skip to main content" link for keyboard users | |
+| `heading-hierarchy` | Sequential h1→h2→h3, no level skips | |
+| `color-not-only` | Never convey information by color alone — add icon or text | |
+| `dynamic-type` | Support system text scaling; no truncation as text grows | |
+| `reduced-motion` | `@media (prefers-reduced-motion: reduce)` wraps all animations | Non-negotiable |
+| `escape-routes` | Cancel/back affordance in all modals and multi-step flows | |
+| `keyboard-shortcuts` | Preserve system accessibility shortcuts | |
+
+---
+
+## Priority 2: Touch & Interaction (CRITICAL)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `touch-target-size` | Min 44×44pt interactive area; expand hit area beyond visual bounds if needed | |
+| `touch-spacing` | Minimum 8px gap between adjacent touch targets | |
+| `hover-vs-tap` | Primary interactions are click/tap; hover is enhancement only | |
+| `loading-buttons` | Disable button during async operations; show spinner or progress | |
+| `error-feedback` | Clear error messages near the problem element | |
+| `cursor-pointer` | `cursor: pointer` on all clickable elements | Web |
+| `tap-delay` | `touch-action: manipulation` to remove 300ms delay | Web |
+| `press-feedback` | Visual feedback on press (opacity, scale, ripple) within 80–150ms | |
+| `drag-threshold` | Movement threshold before starting drag to avoid accidental drags | |
+
+---
+
+## Priority 3: Performance (HIGH)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `image-optimization` | WebP/AVIF, responsive `srcset`/`sizes`, lazy load non-critical | |
+| `image-dimension` | Declare `width`/`height` or `aspect-ratio` to prevent CLS | Core Web Vitals |
+| `font-loading` | `font-display: swap` or `optional`; preload critical fonts only | |
+| `critical-css` | Above-the-fold CSS loads first (inline critical or early stylesheet) | |
+| `bundle-splitting` | Split code by route/feature (React Suspense, dynamic import) | |
+| `reduce-reflows` | Batch DOM reads then writes; no layout thrashing | |
+| `content-jumping` | Reserve space for async content (skeleton screens, aspect-ratio boxes) | |
+| `virtualize-lists` | Virtualize lists of 50+ items | |
+| `debounce-throttle` | Debounce/throttle for scroll, resize, and input events | |
+| `progressive-loading` | Skeleton/shimmer for operations >1s; never a blocking spinner | |
+
+---
+
+## Priority 4: Style Selection (HIGH)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `consistency` | One visual style across all pages; no mid-product style drift | |
+| `no-emoji-icons` | SVG icons only (Heroicons, Lucide, Phosphor); never emojis as icons | |
+| `effects-match-style` | Shadows, blur, radius aligned with chosen style | |
+| `state-clarity` | Hover/pressed/disabled states are visually distinct | |
+| `elevation-consistent` | Consistent shadow scale for cards, sheets, modals | |
+| `icon-style-consistent` | One icon set; consistent stroke weight and corner radius | |
+| `primary-action` | One primary CTA per screen; secondary actions visually subordinate | |
+| `blur-purpose` | Blur indicates background dismissal (modals, sheets); never decorative | |
+
+---
+
+## Priority 5: Layout & Responsive (HIGH)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `viewport-meta` | `width=device-width, initial-scale=1`; never disable zoom | |
+| `mobile-first` | Design mobile-first; scale up to tablet and desktop | |
+| `breakpoint-consistency` | Systematic breakpoints: 375 / 768 / 1024 / 1440 | |
+| `readable-font-size` | Min 16px body on mobile (avoids iOS auto-zoom) | |
+| `line-length-control` | Mobile 35–60 chars; desktop 60–75 chars | |
+| `horizontal-scroll` | No horizontal scroll on mobile | |
+| `spacing-scale` | 4pt/8dp incremental spacing system | |
+| `container-width` | Consistent max-width on desktop (max-w-6xl / 7xl) | |
+| `z-index-management` | Defined layered z-index scale (0 / 10 / 20 / 40 / 100 / 1000) | |
+| `fixed-element-offset` | Fixed navbar/bottom bar reserves safe padding for underlying content | |
+| `viewport-units` | Prefer `min-h-dvh` over `100vh` | |
+| `visual-hierarchy` | Hierarchy via size, spacing, contrast — not color alone | |
+
+---
+
+## Priority 6: Typography & Color (MEDIUM)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `line-height` | `1.5`–`1.75` for body text (`1.6` is the Editorial Sanctuary target) | |
+| `line-length` | `max-width: 65ch` on paragraph containers | |
+| `font-pairing` | Heading and body fonts have distinct personalities | |
+| `font-scale` | Consistent type scale (12 / 14 / 16 / 18 / 24 / 32) | |
+| `weight-hierarchy` | Bold headings (600–700), regular body (400), medium labels (500) | |
+| `color-semantic` | Semantic color tokens (primary, secondary, error, surface); no raw hex in components | |
+| `color-dark-mode` | Dark mode uses desaturated/lighter tonal variants; test contrast independently | |
+| `color-accessible-pairs` | All foreground/background pairs meet 4.5:1 (AA) or 7:1 (AAA) | |
+| `color-not-decorative-only` | Functional colors (error, success) also use icon or text — no color-only meaning | |
+| `letter-spacing` | Avoid tight tracking on body text; track only micro-labels, buttons, uppercase | |
+| `number-tabular` | Tabular/monospaced figures for data columns, prices, timers | |
+
+---
+
+## Priority 7: Animation (MEDIUM)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `duration-timing` | 150–300ms for micro-interactions; complex transitions ≤400ms | |
+| `transform-performance` | Animate `transform` and `opacity` only; never width/height/top/left | |
+| `easing` | `ease-out` for entering; `ease-in` for exiting; never linear for UI | |
+| `motion-meaning` | Every animation expresses cause-effect; no purely decorative motion | |
+| `spring-physics` | Prefer spring/physics curves over cubic-bezier for natural feel | |
+| `exit-faster` | Exit animations 60–70% of enter duration — feels responsive | |
+| `stagger-sequence` | Stagger list/grid entrances 30–50ms per item | |
+| `interruptible` | Animations are interruptible; user action cancels in-progress animation | |
+| `no-blocking-animation` | UI stays interactive during animations; never block input | |
+| `scale-feedback` | Subtle scale (0.95–1.05) on press for tappable cards/buttons | |
+| `layout-shift-avoid` | Animations must not trigger reflow or CLS | |
+| `loading-states` | Skeleton or progress indicator when loading exceeds 300ms | |
+| `excessive-motion` | Animate 1–2 key elements per view max | |
+
+---
+
+## Priority 8: Forms & Feedback (MEDIUM)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `input-labels` | Visible label per input — no placeholder-as-label | |
+| `error-placement` | Error message below the related field | |
+| `submit-feedback` | Loading → then success/error state on submit | |
+| `required-indicators` | Required fields marked (asterisk + sr-only explanation) | |
+| `empty-states` | Helpful message and action when no content | |
+| `toast-dismiss` | Auto-dismiss toasts in 3–5s | |
+| `confirmation-dialogs` | Confirm before all destructive actions | |
+| `disabled-states` | Disabled: reduced opacity (0.38–0.5) + cursor change + semantic attribute | |
+| `progressive-disclosure` | Reveal complex options progressively; don't overwhelm upfront | |
+| `inline-validation` | Validate on blur, not on keystroke; show error only after user finishes | |
+| `password-toggle` | Show/hide toggle for password fields | |
+| `error-clarity` | Error messages state cause + how to fix (not just "Invalid input") | |
+| `focus-management` | After submit error, auto-focus the first invalid field | |
+| `error-summary` | Multiple errors get a summary at top with anchor links to each field | |
+| `toast-accessibility` | Toasts use `aria-live="polite"` — never steal focus | |
+| `undo-support` | Allow undo for destructive or bulk actions | |
+| `multi-step-progress` | Multi-step flows show step indicator; allow back navigation | |
+| `timeout-feedback` | Request timeout shows clear feedback with retry option | |
+
+---
+
+## Priority 9: Navigation Patterns (HIGH)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `back-behavior` | Back navigation is predictable and consistent; preserves scroll/state | |
+| `deep-linking` | All key screens reachable via URL for sharing | |
+| `nav-label-icon` | Navigation items have both icon and text label | |
+| `nav-state-active` | Current location visually highlighted (color, weight, or indicator) | |
+| `nav-hierarchy` | Primary nav vs secondary nav are clearly separated | |
+| `modal-escape` | Modals/dialogs have a clear close affordance | |
+| `search-accessible` | Search easily reachable from top bar or primary nav | |
+| `breadcrumb-web` | Breadcrumbs for 3+ level deep hierarchies | Web |
+| `state-preservation` | Back restores previous scroll position, filter state, and input | |
+| `overflow-menu` | When actions exceed space, use overflow/more menu instead of cramming | |
+| `navigation-consistency` | Navigation placement same across all pages | |
+| `modal-vs-navigation` | Modals are not used for primary navigation flows | |
+| `focus-on-route-change` | After page transition, move focus to main content for screen readers | |
+| `destructive-nav-separation` | Dangerous actions (delete, logout) spatially separated from normal nav | |
+
+---
+
+## Priority 10: Charts & Data (LOW)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `chart-type` | Match chart to data: trend → line, comparison → bar, proportion → pie/donut | |
+| `color-guidance` | Accessible color palettes; no red/green-only pairs (colorblind) | |
+| `data-table` | Table alternative for screen readers; charts alone are not accessible | |
+| `legend-visible` | Always show legend; position near the chart | |
+| `tooltip-on-interact` | Tooltips on hover/focus showing exact values | |
+| `axis-labels` | Label axes with units; avoid truncated labels | |
+| `responsive-chart` | Charts reflow or simplify on small screens | |
+| `empty-data-state` | Meaningful empty state when no data | |
+| `no-pie-overuse` | No pie/donut for >5 categories; use bar chart | |
+| `gridline-subtle` | Grid lines are low-contrast (e.g. gray-200); don't compete with data | |
+| `focusable-elements` | Interactive chart elements are keyboard-navigable | |
+| `screen-reader-summary` | Text summary or aria-label describing chart's key insight | |
+| `tooltip-keyboard` | Tooltip content keyboard-reachable; not hover-only | |
+| `sortable-table` | Data tables support sorting with `aria-sort` | |
+| `animation-optional` | Chart entrance animations respect `prefers-reduced-motion` | |
+
+---
+
+## Quick Decision: When to use this reference
+
+| You're doing | Jump to |
+|---|---|
+| Accessibility review | Priority 1 |
+| Mobile/touch audit | Priority 2 |
+| Performance audit | Priority 3 |
+| Animation review | Priority 7 |
+| Form UX | Priority 8 |
+| Navigation review | Priority 9 |
+| Data visualization | Priority 10 |
+| Full pre-ship review | Use `pre-delivery-checklist.md` |

package/.claude/skills/monodesign/reference/ux-writing.md

@@ -0,0 +1,107 @@
+# UX Writing
+
+## The Button Label Problem
+
+**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
+
+| Bad | Good | Why |
+|-----|------|-----|
+| OK | Save changes | Says what will happen |
+| Submit | Create account | Outcome-focused |
+| Yes | Delete message | Confirms the action |
+| Cancel | Keep editing | Clarifies what "cancel" means |
+| Click here | Download PDF | Describes the destination |
+
+**For destructive actions**, name the destruction:
+- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
+- "Delete 5 items" not "Delete selected" (show the count)
+
+## Error Messages: The Formula
+
+Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
+
+### Error Message Templates
+
+| Situation | Template |
+|-----------|----------|
+| **Format error** | "[Field] needs to be [format]. Example: [example]" |
+| **Missing required** | "Please enter [what's missing]" |
+| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
+| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
+| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
+
+### Don't Blame the User
+
+Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
+
+## Empty States Are Opportunities
+
+Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
+
+## Voice vs Tone
+
+**Voice** is your brand's personality, consistent everywhere.
+**Tone** adapts to the moment.
+
+| Moment | Tone Shift |
+|--------|------------|
+| Success | Celebratory, brief: "Done! Your changes are live." |
+| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
+| Loading | Reassuring: "Saving your work..." |
+| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
+
+**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
+
+## Writing for Accessibility
+
+**Link text** must have standalone meaning: "View pricing plans" not "Click here". **Alt text** describes information, not the image: "Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
+
+## Writing for Translation
+
+### Plan for Expansion
+
+German text is ~30% longer than English. Allocate space:
+
+| Language | Expansion |
+|----------|-----------|
+| German | +30% |
+| French | +20% |
+| Finnish | +30-40% |
+| Chinese | -30% (fewer chars, but same width) |
+
+### Translation-Friendly Patterns
+
+Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
+
+## Consistency: The Terminology Problem
+
+Pick one term and stick with it:
+
+| Inconsistent | Consistent |
+|--------------|------------|
+| Delete / Remove / Trash | Delete |
+| Settings / Preferences / Options | Settings |
+| Sign in / Log in / Enter | Sign in |
+| Create / Add / New | Create |
+
+Build a terminology glossary and enforce it. Variety creates confusion.
+
+## Avoid Redundant Copy
+
+If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
+
+## Loading States
+
+Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
+
+## Confirmation Dialogs: Use Sparingly
+
+Most confirmation dialogs are design failures; consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
+
+## Form Instructions
+
+Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
+
+---
+
+**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.

package/.claude/skills/monomotion/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: monomotion
+description: HTML-native animation system using GSAP — timeline-driven, API-controllable animations that run in the browser without video rendering or React. Covers timeline control, WebSocket/REST-driven playback, effects, and sequencing.
+version: 1.0.0
+triggers:
+  - /monomotion
+  - /animate
+  - /animation
+  - make an animation
+  - create an animation
+  - add animation
+  - build animation
+  - animate this
+  - animate the
+  - web animation
+  - html animation
+  - browser animation
+  - motion graphics
+  - animated ui
+  - timeline animation
+  - gsap
+  - control animation
+  - api animation
+  - animate via api
+  - playback control
+  - animation controller
+  - animated intro
+  - animated outro
+  - transition animation
+  - scroll animation
+  - text animation
+  - svg animation
+  - animate on scroll
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# Monomotion — HTML Animation with GSAP
+
+API-controllable, HTML-native animation using GSAP. No React, no video rendering — animations run live in the browser and are fully controllable via JavaScript API, WebSocket, or REST.
+
+## Core Philosophy
+
+- Animations are **timelines** — sequences of tweens with precise timing
+- Timelines are **pausable, seekable, reversible** at any point
+- Control surfaces (API, WebSocket, UI) are **decoupled** from animation definitions
+- CSS transitions and keyframes are **not used** — GSAP owns all motion
+
+## Setup
+
+```html
+<!-- CDN — drop into any HTML file -->
+<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
+
+<!-- With ScrollTrigger plugin -->
+<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
+```
+
+```bash
+# npm install
+npm install gsap
+```
+
+```js
+import { gsap } from "gsap";
+```
+
+## Basic Timeline
+
+```js
+const tl = gsap.timeline({ paused: true });
+
+tl.to(".box", { x: 200, duration: 0.8, ease: "power2.out" })
+  .to(".box", { opacity: 0, duration: 0.4 }, "+=0.2")
+  .from(".title", { y: -50, autoAlpha: 0, duration: 0.6 }, "<");
+```
+
+**Position parameter shortcuts:**
+- `"+=0.2"` — 0.2s after previous tween ends
+- `"-=0.1"` — 0.1s before previous tween ends
+- `"<"` — same start time as previous tween
+- `"1.5"` — absolute 1.5s mark in timeline
+
+## Playback Control API
+
+```js
+tl.play();             // play forward from current position
+tl.pause();            // freeze
+tl.resume();           // resume from paused position
+tl.reverse();          // play backward from current position
+tl.restart();          // jump to start and play
+tl.seek(1.5);          // jump to 1.5s (no play)
+tl.progress(0.5);      // jump to 50% of total duration
+tl.timeScale(2);       // 2× speed
+tl.timeScale(0.5);     // half speed
+
+// Read state
+tl.time();             // current time in seconds
+tl.progress();         // 0–1
+tl.duration();         // total duration
+tl.isActive();         // true if currently playing
+```
+
+## Named Labels for Scene Control
+
+```js
+tl.addLabel("intro", 0)
+  .addLabel("reveal", 1.5)
+  .addLabel("outro", 3.0);
+
+// Jump to scene
+tl.seek("reveal");
+tl.play("outro");
+```
+
+## API-Driven Control
+
+See [rules/api-control.md](rules/api-control.md) for WebSocket, REST, and SSE control patterns.
+
+## Effects & Presets
+
+See [rules/effects.md](rules/effects.md) for reusable fade, slide, scale, and reveal effects.
+
+## Sequencing & Staggering
+
+See [rules/sequencing.md](rules/sequencing.md) for staggered lists, cascades, and orchestrated sequences.
+
+## Text Animations
+
+See [rules/text.md](rules/text.md) for character-by-character, word-by-word, and typewriter effects.
+
+## Scroll-Driven Animations
+
+See [rules/scroll.md](rules/scroll.md) for ScrollTrigger integration — scrub, pin, and enter/leave triggers.
+
+## SVG Animations
+
+See [rules/svg.md](rules/svg.md) for path drawing, morphing, and SVG-specific techniques.
+
+## Integration Patterns
+
+See [rules/integration.md](rules/integration.md) for embedding monomotion in dashboards, iframes, and web components.