add llms docs; add type hints

.gitattributes

@@ -2,3 +2,4 @@
 calcit.cirru -diff linguist-generated
 yarn.lock -diff linguist-generated
 Agents.md -diff linguist-generated
+llms/*.md -diff linguist-generated

.github/workflows/tests.yaml

@@ -12,10 +12,15 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
-    - uses: actions/setup-node@v4
+    - uses: actions/setup-node@v6
       with:
         node-version: 24
-        cache: yarn
+
+    - name: Enable Corepack
+      run: |
+        corepack enable
+        corepack prepare yarn@4.12.0 --activate
+        yarn --version
 
     - uses: calcit-lang/setup-cr@0.0.8
 

.gitignore

@@ -9,3 +9,5 @@ yarn-error.log
 tmp/
 
 draft/
+
+.yarn/*.gz

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

deps.cirru

@@ -1,5 +1,5 @@
 
-{} (:calcit-version |0.10.6)
+{} (:calcit-version |0.11.5)
   :dependencies $ {} (|calcit-lang/calcit-test |0.0.6)
     |calcit-lang/lilac |main
-    |calcit-lang/memof |0.0.17
+    |calcit-lang/memof |0.0.22

docs/Respo-Agent.md

@@ -266,18 +266,48 @@ cr libs readme respo
 caps
 ```
 
-### 7. Code Analysis
+### 7. Architectural Exploration (Structure & Patterns)
+
+To quickly understand a project's architecture, combine **Top-Down call graphs** with **Pattern-based structure search**.
+
+#### A. Top-Down: Call Graph Analysis
+
+Use `call-graph` to visualize the component tree and data flow starting from an entry point.
+
+```bash
+# Visualize the app structure from the render entry point
+cr analyze call-graph --root respo.app.core/render-app! --ns-prefix respo.app. --max-depth 3
+
+# This reveals the component hierarchy:
+# └── render-app!
+#     ├── comp-container
+#     │   ├── comp-todolist
+#     │   │   ├── comp-task
+#     │   │   └── comp-wrap
+#     └── dispatch! -> updater
+```
+
+#### B. Pattern-Based: Structure Search
+
+Use `search-expr` to find functional patterns (like state management or event handling) across the whole project.
 
 ```bash
-# Call graph analysis from init-fn (or custom root)
-cr analyze call-graph
-cr analyze call-graph --root app.main/main! --ns-prefix app. --include-core --max-depth 5 --format json
+# How is state being navigated?
+cr query search-expr '>> states' -l
 
-# Call count statistics
-cr analyze count-calls
-cr analyze count-calls --root app.main/main! --ns-prefix app. --include-core --format json --sort count
+# Where are local state changes dispatched?
+cr query search-expr 'd! cursor' -l
+
+# Find all component event handler signatures
+cr query search-expr 'fn (e d!)' -l
 ```
 
+**Strategy:**
+
+1. Use `call-graph` to find **WHO** calls **WHOM**.
+2. Use `search-expr` to find **HOW** certain features are implemented project-wide.
+3. Use `query usages` to find **WHERE** a specific function is integrated.
+
 ---
 
 ## Development Workflow for LLM Agents
@@ -449,6 +479,8 @@ list-> $ {}
 
 ### 5. Styling Pattern
 
+**A. Dynamic Inline Styles (Style Maps)**
+
 ```cirru
 ; Define styles as maps
 def style-container $ {}
@@ -469,6 +501,52 @@ let
   extended
 ```
 
+**B. Static CSS Styles with `defstyle` (Recommended for Performance)**
+
+`defstyle` is a macro that generates CSS classes and injects them into `<style>` tags. Use it for static styles that don't need runtime computation.
+
+```cirru
+; Import from respo.css
+ns my.namespace
+  :require (respo.css :refer $ defstyle)
+
+; Basic usage: & refers to current element
+defstyle style-button $ {}
+  |& $ {} (:padding "|8px 16px") (:border-radius "|4px")
+    :background-color $ hsl 200 80 50
+    :color "|white"
+
+; Pseudo-classes: :hover, :focus, :active, etc.
+defstyle style-link $ {}
+  |& $ {} (:color "|blue") (:text-decoration :none)
+  |&:hover $ {} (:text-decoration :underline)
+
+; Pseudo-elements: ::before, ::after
+defstyle style-text $ {}
+  |& $ {} (:font-size "|14px") (:line-height "|1.6")
+  |&::before $ {} (:content "|\"→ \"")
+
+; Media queries using 'contained
+defstyle style-responsive $ {}
+  |& $ {} (:font-family "|Avenir,Verdana")
+  |& $ {} ('contained "|@media only screen and (max-width: 600px)")
+    :background-color $ hsl 0 0 90
+
+; Usage in component (returns className string)
+div
+  {} $ :class-name style-button
+  <> "|Click Me"
+```
+
+**Key Points:**
+
+- `|&` refers to the current element (required)
+- Use string prefix `|` for CSS selectors like `|&:hover`, `|&::before`
+- `'contained` for media queries and container queries
+- `defstyle` generates unique class names automatically
+- Styles are injected into `<head>` before render
+- For SSR: read from `@*style-list-in-nodejs` to extract CSS
+
 **Testing Style to String Conversion:**
 
 ```bash
@@ -808,12 +886,10 @@ cr query ns namespace-name  # Check imports
 ### ⚠️ Critical Rules
 
 1. **NEVER directly edit `calcit.cirru` or `compact.cirru`** with text editors
-
    - Use `cr edit` commands instead
    - These are serialized AST structures, not human-readable code
 
 2. **ALWAYS use relative paths for documentation links**
-
    - Use `../` and `../../` for navigation
    - This allows easy file discovery for LLM tools