@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/streamlit-dev/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: streamlit-dev
+description: Build production-ready Streamlit dashboards with best-practice patterns, caching, components, and theming. Use when implementing any Streamlit page, component, chart, or UI feature.
+---
+
+# Streamlit Development Skill
+
+## When to Use
+
+Invoke this skill when:
+- Creating a new Streamlit page
+- Building or modifying UI components
+- Adding charts or KPIs
+- Implementing caching for data or resources
+- Applying consistent branding/theming
+- Fixing UI/UX issues in Streamlit apps
+
+---
+
+## Page Template (MANDATORY)
+
+Every Streamlit page MUST follow this structure:
+
+```python
+"""Page Title - Brief description."""
+import streamlit as st
+
+# Page config MUST be the first Streamlit call
+st.set_page_config(page_title="PageName", page_icon="icon", layout="wide")
+
+# If using a shared header/navigation component:
+# from components.header import render_header
+# render_header(current_page="PageName")
+
+# --- Page content below ---
+```
+
+### Key Rules
+- `st.set_page_config()` MUST be the first Streamlit command
+- Choose navigation pattern: sidebar (default) or custom header
+- Always set `layout="wide"` for dashboards
+
+---
+
+## Branding & Theming
+
+### Color Palette (Configure Per Project)
+
+```python
+BRAND_PRIMARY = "<BRAND_PRIMARY>"     # Primary accent color
+BRAND_DARK = "<BRAND_DARK>"           # Headings, dark text
+BRAND_LIGHT = "<BRAND_LIGHT>"         # Page/card backgrounds
+GRAY_500 = "#6C757D"                  # Secondary text
+GRAY_100 = "#E9ECEF"                  # Borders, dividers
+SUCCESS = "#22C55E"                   # Positive indicators
+WARNING = "#F59E0B"                   # Warning indicators
+ERROR = "#EF4444"                     # Error/negative indicators
+```
+
+### 60-30-10 Color Rule
+- **60%**: Light backgrounds (white, `<BRAND_LIGHT>`)
+- **30%**: Dark text and structure (`<BRAND_DARK>`)
+- **10%**: Primary accents (`<BRAND_PRIMARY>`)
+
+---
+
+## Charts (Plotly)
+
+### CRITICAL: Avoid "undefined" Labels
+
+```python
+# NEVER pass title directly to px functions
+fig = px.pie(data, names="cat", values="count")
+fig.update_layout(title="Chart Title", height=300)
+```
+
+### Branded Charts
+
+```python
+import plotly.express as px
+
+CHART_COLORS = ["<BRAND_PRIMARY>", "<BRAND_DARK>", "#6B7280", "#9CA3AF", "#D1D5DB"]
+
+def create_chart(df, x, y, chart_type="bar", title=None):
+    if chart_type == "bar":
+        fig = px.bar(df, x=x, y=y, color_discrete_sequence=CHART_COLORS)
+    elif chart_type == "line":
+        fig = px.line(df, x=x, y=y, color_discrete_sequence=CHART_COLORS)
+    elif chart_type == "pie":
+        fig = px.pie(df, names=x, values=y, color_discrete_sequence=CHART_COLORS)
+
+    fig.update_layout(
+        title=title if title and title.strip() else "",
+        template="plotly_white",
+        font_family="Inter, sans-serif",
+        title_font_size=18,
+        legend_title_text="",
+        hovermode="x unified",
+    )
+    return fig
+
+st.plotly_chart(fig, use_container_width=True)
+```
+
+---
+
+## Caching Strategy
+
+### Data Caching (serialized copy per caller)
+
+```python
+from datetime import timedelta
+
+@st.cache_data(ttl=timedelta(minutes=15), show_spinner="Loading data...")
+def load_orders() -> pd.DataFrame:
+    return repo.get_all_orders()
+```
+
+### Resource Caching (shared singleton)
+
+```python
+@st.cache_resource
+def get_repository():
+    return OrdersRepository()
+```
+
+### When to Use Each
+
+| Decorator | Use For | Returns |
+|-----------|---------|---------|
+| `@st.cache_data` | DataFrames, lists, dicts | Serialized copy |
+| `@st.cache_resource` | Connections, models, adapters | Same object ref |
+
+---
+
+## Component Patterns
+
+### KPI Cards
+
+```python
+def render_kpi_row(kpis: list[dict]):
+    cols = st.columns(len(kpis))
+    for col, kpi in zip(cols, kpis):
+        with col:
+            st.metric(label=kpi["label"], value=kpi["value"], delta=kpi.get("delta"))
+```
+
+### Data Tables
+
+```python
+st.dataframe(
+    df, use_container_width=True, hide_index=True,
+    column_config={
+        "id": st.column_config.TextColumn("ID", width="small"),
+        "created_at": st.column_config.DatetimeColumn("Created", format="DD/MM/YYYY HH:mm"),
+    }
+)
+```
+
+### Pagination
+
+```python
+def paginate_df(df, page, per_page):
+    start = (page - 1) * per_page
+    return df.iloc[start:start + per_page]
+
+total_pages = (len(df) - 1) // per_page + 1
+page = st.number_input(f"Page (of {total_pages})", 1, total_pages, 1)
+st.dataframe(paginate_df(df, page, per_page))
+```
+
+---
+
+## Session State
+
+```python
+def init_session_state():
+    defaults = {"authenticated": False, "selected_filters": {}, "page_number": 1}
+    for key, value in defaults.items():
+        if key not in st.session_state:
+            st.session_state[key] = value
+
+def on_filter_change():
+    st.session_state.page_number = 1
+
+st.selectbox("Category", options=categories, key="filter", on_change=on_filter_change)
+```
+
+---
+
+## Forms
+
+```python
+with st.form("order_form", clear_on_submit=True):
+    customer_id = st.text_input("Customer ID*")
+    description = st.text_area("Description*", max_chars=2000)
+    priority = st.slider("Priority", 1, 5, 3)
+
+    if st.form_submit_button("Submit", type="primary"):
+        if not customer_id or not description:
+            st.error("Please fill in all required fields")
+        else:
+            save_order(customer_id, description, priority)
+            st.success("Submitted!")
+```
+
+---
+
+## Error Handling
+
+```python
+try:
+    data = load_data()
+    render_dashboard(data)
+except ConnectionError:
+    st.error("Unable to connect to database. Please try again later.")
+except Exception:
+    st.error("An unexpected error occurred. Please contact support.")
+```
+
+### Empty State
+
+```python
+if df.empty:
+    st.info("No data found for the selected filters.")
+    return
+```
+
+---
+
+## Performance Tips
+
+1. **Cache aggressively** -- data fetches, computations, model loading
+2. **Lazy load** -- only fetch data when needed
+3. **Paginate** -- never dump 10K+ rows into `st.dataframe`
+4. **Minimize reruns** -- use `st.session_state` and callbacks
+5. **Use `st.fragment`** -- for widgets that shouldn't rerun the whole page
+
+---
+
+## Framework Limitations — Floating UI (CRITICAL)
+
+Streamlit wraps all `st.markdown(unsafe_allow_html=True)` in **20-30 nested `<div>` containers**, breaking CSS `position: fixed/absolute`. **Do NOT attempt CSS-only solutions for floating elements.**
+
+| Approach | Use For | Limitations |
+|----------|---------|-------------|
+| `st.markdown(unsafe_allow_html=True)` | Inline styling, cards, badges | Wrapped in nested divs; no DOM control |
+| `st.html()` | Self-contained HTML snippets | Sandboxed iframe; no access to parent DOM |
+| `components.declare_component()` | **Floating UI, chat widgets, FABs, toasts, modals** | Requires HTML/JS file; bi-directional via `setComponentValue` |
+
+**Pattern:** Use `declare_component()` with `height=0` to create an invisible iframe, then inject elements into `window.parent.document.body` from the component's JavaScript.
+
+> CSS `position: fixed` and `z-index` escalation will **never work** reliably in Streamlit due to its DOM wrapping architecture.
+
+---
+
+## Checklist
+
+- [ ] `st.set_page_config()` is the first Streamlit call
+- [ ] Navigation pattern applied consistently
+- [ ] Brand colors applied (60-30-10 rule)
+- [ ] Charts use `update_layout(title=...)` not `title=` in px call
+- [ ] Data cached with appropriate TTL
+- [ ] Empty states show helpful messages
+- [ ] Error handling with user-friendly messages
+- [ ] Large datasets paginated
+- [ ] Session state initialized with defaults
+- [ ] Forms validate required fields

package/bundles/antigravity-plugin-extras/skills/svg-create/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: svg-create
+context: fork
+description: "Brand-themed SVG diagrams with consistent color palette and accessible design"
+---
+
+# SVG Creation Skill
+
+Create professional SVG diagrams with consistent brand theming.
+
+> **Project Context** — Read `project-config.md` in the repo root for brand tokens, color palette, and project metadata.
+
+## When to Use
+
+- Workflow diagrams and flowcharts
+- Architecture diagrams
+- Decision trees
+- Process visualizations
+- Quick reference cards
+- Any visual that needs to be version-controlled
+
+## SVG Best Practices
+
+### Document Structure
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 600">
+  <defs>
+    <!-- Reusable styles and markers -->
+    <style>
+      .title { font: bold 24px 'Segoe UI', Arial, sans-serif; fill: #1F2937; }
+      .text { font: 14px 'Segoe UI', Arial, sans-serif; fill: #374151; }
+    </style>
+    <marker id="arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#6B7280"/>
+    </marker>
+  </defs>
+  
+  <!-- Background -->
+  <rect width="800" height="600" fill="white"/>
+  
+  <!-- Content here -->
+</svg>
+```
+
+### Print-Friendly Design
+
+**CRITICAL**: Always design for print compatibility:
+
+```xml
+<!-- ✅ GOOD: Light backgrounds for print -->
+<rect fill="white"/>
+<rect fill="#F8FAFC"/>  <!-- Very light gray -->
+<rect fill="#ECFDF5"/>  <!-- Very light green -->
+
+<!-- ❌ BAD: Dark backgrounds don't print well -->
+<rect fill="#1F2937"/>  <!-- Dark navy - avoid -->
+<rect fill="black"/>     <!-- Never for large areas -->
+```
+
+### Color Palette
+
+```xml
+<!-- Primary Colors -->
+#E10A0A    <!-- Primary Red - primary accent -->
+#1F2937    <!-- Navy - text only, not backgrounds -->
+
+<!-- Scenario Colors (use light fills) -->
+#ECFDF5    <!-- Light green - new/create -->
+#10B981    <!-- Green - borders/accents -->
+#EEF2FF    <!-- Light indigo - existing/continue -->
+#6366F1    <!-- Indigo - borders/accents -->
+#F0F9FF    <!-- Light blue - simple/quick -->
+#0EA5E9    <!-- Blue - borders/accents -->
+#FFF7ED    <!-- Light orange - warning/emergency -->
+#F97316    <!-- Orange - borders/accents -->
+#FEF3C7    <!-- Light yellow - help/info -->
+#F59E0B    <!-- Amber - borders/accents -->
+
+<!-- Neutral Colors -->
+#374151    <!-- Text color -->
+#6B7280    <!-- Secondary text -->
+#E5E7EB    <!-- Light border -->
+#F8FAFC    <!-- Light background -->
+```
+
+### Common Patterns
+
+#### Numbered Steps
+
+```xml
+<!-- Step circle with number -->
+<circle cx="50" cy="100" r="18" fill="#10B981"/>
+<text x="50" y="106" text-anchor="middle" fill="white" 
+      font-weight="bold" font-size="16">1</text>
+```
+
+#### Connection Arrows
+
+```xml
+<!-- Define marker in <defs> first -->
+<marker id="arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+  <polygon points="0 0, 10 3.5, 0 7" fill="#6B7280"/>
+</marker>
+
+<!-- Use the arrow -->
+<line x1="100" y1="50" x2="100" y2="100" stroke="#6B7280" 
+      stroke-width="2" marker-end="url(#arrow)"/>
+```
+
+#### Rounded Boxes
+
+```xml
+<!-- Container box -->
+<rect x="30" y="80" width="400" height="200" rx="12" 
+      fill="#ECFDF5" stroke="#10B981" stroke-width="2"/>
+
+<!-- Content box -->
+<rect x="50" y="100" width="360" height="40" rx="6" 
+      fill="white" stroke="#10B981" stroke-width="1"/>
+```
+
+#### Text Styling
+
+```xml
+<!-- Title -->
+<text x="400" y="40" text-anchor="middle" 
+      font-size="24" font-weight="bold" fill="#1F2937">Title</text>
+
+<!-- Monospace code -->
+<text font-family="'Courier New', monospace" fill="#E10A0A">/command</text>
+
+<!-- Agent reference -->
+<text font-weight="bold" fill="#7C3AED">@agent-name</text>
+
+<!-- File path -->
+<text font-family="'Courier New', monospace" fill="#059669">plans/</text>
+```
+
+### Responsive ViewBox
+
+Calculate viewBox from content:
+- **Width**: Rightmost element + padding (usually 30-50px)
+- **Height**: Bottom element + padding (usually 30-50px)
+
+```xml
+<!-- For 800x600 content with 30px padding -->
+<svg viewBox="0 0 860 660">
+```
+
+### Font Stack
+
+Always specify fallbacks:
+
+```css
+font-family: 'Segoe UI', Arial, sans-serif;  /* Text */
+font-family: 'Courier New', monospace;        /* Code */
+```
+
+## Reliable Text & Layout (No Clipping)
+
+To keep project diagrams sharp and readable (and avoid cropped text):
+
+### Text box sizing
+
+For a `<text>` block (optionally with `<tspan>` lines):
+
+- `maxLineLen` = length of the longest line.
+- `fontSize` = size in px.
+- `lines` = number of lines.
+
+Use:
+
+```text
+baseWidth   = maxLineLen * fontSize * 0.7
+cardWidth   = ceil(baseWidth) + 16      // horizontal padding
+
+baseHeight  = fontSize * 1.2 * lines
+cardHeight  = ceil(baseHeight * 1.1)    // ~10% vertical padding
+```
+
+Size the surrounding `<rect>` to at least `cardWidth × cardHeight`. Do not let text touch the edges.
+
+### clipPath usage
+
+- Prefer simple rounded boxes without clipping.
+- If you use `<clipPath>` for a lane or card:
+  - Make the clip rect **larger** than the visible card by 8–12px on all sides.
+  - Never set the clip rect tighter than the text block; otherwise labels like “More than ~5 files or new page/component/source?” will be cut.
+
+### Card Example
+
+```xml
+<defs>
+  <clipPath id="lane1-clip">
+    <rect x="20" y="80" width="300" height="100" rx="8"/>
+  </clipPath>
+</defs>
+
+<g clip-path="url(#lane1-clip)">
+  <rect x="30" y="90" width="280" height="80" rx="8"
+        fill="#ECFDF5" stroke="#10B981" stroke-width="2"/>
+  <text x="170" y="116" text-anchor="middle" class="text">
+    <tspan x="170" dy="0">Lane 1: Quick Fix</tspan>
+    <tspan x="170" dy="18">~1 session, &lt;10 files</tspan>
+  </text>
+</g>
+```
+
+The `lane1-clip` rectangle is larger than the card, so text won’t clip even if it grows slightly.
+
+## Checklist Before Creating
+
+- [ ] Using white or very light fills for backgrounds
+- [ ] Text is at least 11px for readability
+- [ ] Text blocks have generous padding; no line touches card edges or clip paths
+- [ ] Contrast ratio is print-safe
+- [ ] ViewBox sized to content + padding
+- [ ] Arrow markers defined in `<defs>`
+- [ ] Font families have fallbacks
+- [ ] File saved with `.svg` extension
+
+## Example: Simple Flowchart
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 200">
+  <defs>
+    <marker id="arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#6B7280"/>
+    </marker>
+  </defs>
+  
+  <rect width="400" height="200" fill="white"/>
+  
+  <!-- Start -->
+  <rect x="20" y="80" width="100" height="40" rx="8" fill="#ECFDF5" stroke="#10B981" stroke-width="2"/>
+  <text x="70" y="105" text-anchor="middle" fill="#374151">Start</text>
+  
+  <!-- Arrow -->
+  <line x1="120" y1="100" x2="170" y2="100" stroke="#6B7280" stroke-width="2" marker-end="url(#arrow)"/>
+  
+  <!-- End -->
+  <rect x="180" y="80" width="100" height="40" rx="8" fill="#EEF2FF" stroke="#6366F1" stroke-width="2"/>
+  <text x="230" y="105" text-anchor="middle" fill="#374151">End</text>
+</svg>
+```
+
+## Related Resources
+
+- Agent: `@svg-diagram` - For complex, multi-element diagrams
+- Tool: Mermaid - For quick code-based diagrams (then export to SVG)