gtm-ui-native 0.0.3.1__tar.gz

gtm_ui_native-0.0.3.1/.agents/skills/components/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: components
+description: >
+  Buridan Native UI component system built on Reflex. Use when creating user
+  interfaces, selecting Native components, composing layouts, using rx.el.*
+  HTML elements, modifying component APIs, adding components, or answering
+  questions about UI development.
+---
+
+# Buridan Native Components
+
+This skill covers building user interfaces with Buridan Native.
+
+Buridan Native provides reusable UI components built on top of Reflex.
+
+When building UI, prefer:
+
+1. Buridan Native components for common UI patterns.
+2. Reflex HTML elements (`rx.el.*`) for custom structure, layouts, and missing pieces.
+
+The documentation is the source of truth.
+
+---
+
+# Component Strategy
+
+## Prefer Buridan Native Components
+
+Use existing Buridan Native components whenever possible.
+
+Native components provide:
+
+- Consistent styling
+- Common behavior
+- Accessibility patterns
+- Reusable APIs
+- Framework conventions
+
+Before creating custom UI:
+
+1. Check whether Buridan Native already provides a component.
+2. Use the existing component if it matches the use case.
+3. Compose components together when possible.
+
+Do not recreate existing Native components using raw HTML.
+
+Examples:
+
+Use:
+
+```python
+button(...)
+```
+
+instead of:
+
+```python
+rx.el.button(...)
+```
+
+when a Native button component exists.
+
+Use:
+
+```python
+dialog(...)
+```
+
+instead of manually creating dialog markup.
+
+---
+
+# Reflex HTML Elements (`rx.el.*`)
+
+Buridan Native is built on Reflex, which provides access to HTML elements through:
+
+```python
+rx.el.*
+```
+
+Use `rx.el.*` for:
+
+- Page structure
+- Semantic HTML
+- Custom layouts
+- Small UI compositions
+- Wrapping Native components
+- Elements without a dedicated Native component
+
+Examples:
+
+```python
+rx.el.div(
+    rx.el.h1("Dashboard"),
+    rx.el.p("Welcome back")
+)
+```
+
+```python
+rx.el.section(
+    native.card(...)
+)
+```
+
+```python
+rx.el.header(
+    rx.el.nav(...)
+)
+```
+
+Common elements include:
+
+```text
+rx.el.div
+rx.el.span
+rx.el.p
+rx.el.h1
+rx.el.h2
+rx.el.h3
+rx.el.a
+rx.el.img
+rx.el.form
+rx.el.input
+rx.el.section
+rx.el.header
+rx.el.footer
+rx.el.nav
+```
+
+---
+
+# Layouts
+
+For layouts and page composition, prefer `rx.el.*` unless Buridan Native provides a dedicated layout component.
+
+Examples:
+
+```python
+rx.el.div(
+    sidebar,
+    content
+)
+```
+
+```python
+rx.el.section(
+    header,
+    body
+)
+```
+
+Use Native layout primitives when they exist.
+
+Do not create unnecessary wrapper components for simple layout.
+
+Prefer:
+
+```python
+rx.el.div(
+    native.card(...),
+    native.button(...)
+)
+```
+
+over:
+
+```python
+DashboardContainer(
+    DashboardCard(),
+    DashboardButton()
+)
+```
+
+unless the pattern is reused and has meaningful behavior.
+
+---
+
+# Component Categories
+
+## Actions
+
+Use Native components for:
+
+- Buttons
+- Links
+- User actions
+- Controls
+
+Avoid manually recreating interactive controls with HTML.
+
+---
+
+## Forms
+
+Use Native components for:
+
+- Inputs
+- Selectors
+- Toggles
+- Form controls
+
+Use `rx.el.*` for:
+
+- Form structure
+- Labels
+- Custom grouping
+
+Example:
+
+```python
+rx.el.form(
+    native.input(...),
+    native.button(...)
+)
+```
+
+---
+
+## Content
+
+Use Native components for:
+
+- Cards
+- Alerts
+- Badges
+- Tables
+- User-facing patterns
+
+Use `rx.el.*` for:
+
+- Text structure
+- Semantic grouping
+- Custom markup
+
+---
+
+# Creating New Components
+
+Before adding a new Buridan Native component:
+
+1. Confirm the pattern does not already exist.
+2. Check similar components.
+3. Determine whether composition is enough.
+4. Follow existing component conventions.
+5. Add documentation.
+6. Add examples where appropriate.
+
+Create a new component when it:
+
+- Is reused across applications.
+- Has meaningful behavior.
+- Has a stable API.
+- Represents a common UI pattern.
+
+Do not create components only to wrap simple HTML.
+
+---
+
+# Component Documentation
+
+Component documentation:
+
+https://native.buridan.dev/components/
+
+Repository documentation:
+
+```text
+docs/components/
+```
+
+URL pattern:
+
+```text
+docs/components/<component>.md
+```
+
+maps to:
+
+```text
+https://native.buridan.dev/components/<component>
+```
+
+Example:
+
+```text
+docs/components/button.md
+```
+
+maps to:
+
+```text
+https://native.buridan.dev/components/button
+```
+
+---
+
+# When To Use This Skill
+
+Use this skill when:
+
+- Building UI
+- Choosing between components
+- Creating layouts
+- Working with `rx.el.*`
+- Adding new components
+- Understanding Buridan Native APIs
+- Migrating UI code
+
+---
+
+# Do Not Use This Skill For
+
+Do not use this skill for:
+
+- Application state
+- Event architecture
+- Theming systems
+- Chart configuration
+- Internal framework architecture
+
+Use the specialized skill instead.

gtm_ui_native-0.0.3.1/.agents/skills/getting-started/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: getting-started
+description: >
+  Native framework setup and onboarding. Use when creating a new Native
+  application, installing dependencies, configuring the environment, using
+  the CLI, or explaining the basic Native development workflow.
+---
+
+# Getting Started
+
+This skill helps answer questions about installing, configuring, and starting
+development with Native.
+
+The documentation is the source of truth.
+
+## References
+
+### Introduction
+
+Repository:
+
+```text
+docs/getting_started/introduction.md
+```
+
+Documentation:
+
+https://native.buridan.dev/docs/getting-started/introduction
+
+---
+
+### Installation
+
+Repository:
+
+```text
+docs/getting_started/installation.md
+```
+
+Documentation:
+
+https://native.buridan.dev/docs/getting-started/installation
+
+---
+
+### CLI
+
+Repository:
+
+```text
+docs/getting_started/cli.md
+```
+
+Documentation:
+
+https://native.buridan.dev/docs/getting-started/cli
+
+---
+
+### Desktop
+
+Repository:
+
+```text
+docs/getting_started/desktop.md
+```
+
+Documentation:
+
+https://native.buridan.dev/docs/getting-started/desktop
+
+---
+
+### JavaScript Integration
+
+Repository:
+
+```text
+docs/getting_started/javascript.md
+```
+
+Documentation:
+
+https://native.buridan.dev/docs/getting-started/javascript
+
+---
+
+### Changelog
+
+Repository:
+
+```text
+docs/getting_started/changelog.md
+```
+
+Documentation:
+
+https://native.buridan.dev/docs/getting-started/changelog
+
+---
+
+# When To Use This Skill
+
+Use this skill when the user asks about:
+
+- Installing Native
+- Creating a new Native project
+- Setting up a development environment
+- Running a Native application
+- Using Native CLI commands
+- Understanding the basic project structure
+- Troubleshooting setup issues
+
+# Guidance
+
+When helping with setup:
+
+1. Check the documented workflow first.
+2. Prefer official Native commands and patterns.
+3. Avoid suggesting undocumented configuration.
+4. Include the relevant documentation link when useful.
+5. Keep examples consistent with the current Native API.
+
+# Do Not Use This Skill For
+
+Do not use this skill for:
+
+- Building UI components
+- Component APIs
+- Application state
+- Events
+- Styling and theming
+- Charts
+- Internal architecture
+
+Use the more specific skill instead.

gtm_ui_native-0.0.3.1/.agents/skills/rwx/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rwx
+description: Authenticate and use the RWX CLI. Run RWX CI on the working tree (including uncommitted changes), type-check with pyright/pyrefly without a local venv, read run results and logs, and create, lint, or modify `.rwx/*.yml`. Use when asked about RWX, when "CI failed" or "CI is red", or when asked to run tests or fetch logs on RWX.
+---
+
+# RWX CLI in this repo
+
+CI definitions live in `.rwx/`. Merge gates run in GitHub Actions and the Trunk
+Merge Queue (see `AGENTS.md`). The RWX pipelines are manual only, with no PR or
+push trigger, so they are not required statuses.
+
+| File | Purpose |
+| --- | --- |
+| `.rwx/pyright.yml` | pyright with a synced venv |
+| `.rwx/pyrefly.yml` | pyrefly with a synced venv |
+
+## Auth: injected tokens, one per RWX workspace
+
+Env vars named `RWX_ACCESS_TOKEN_<SUFFIX>` or `RWC_ACCESS_TOKEN_<SUFFIX>` are
+injected. Each token is scoped to one RWX workspace; `<SUFFIX>` is the
+workspace name, uppercased. List the names without values:
+
+```bash
+env | grep -E '^RW[XC]_ACCESS_TOKEN_' | cut -d= -f1
+```
+
+The CLI reads only `RWX_ACCESS_TOKEN` (or `--access-token`). Export the token
+whose suffix matches the repo owner (from the `origin` URL, uppercased). Never
+print it:
+
+```bash
+OWNER=$(git remote get-url origin | sed -E 's#.*[:/]([^/]+)/[^/]+(\.git)?$#\1#' | tr a-z A-Z)
+export RWX_ACCESS_TOKEN="$(printenv "RWX_ACCESS_TOKEN_$OWNER" || printenv "RWC_ACCESS_TOKEN_$OWNER")"
+rwx whoami   # confirms organization and user, does not show the token
+```
+
+The shell does not persist between tool calls, so export per command. A run,
+task, or log ID only resolves under the workspace that owns it. On
+not-found or unauthorized, try the other token. Without any token,
+`rwx login` authorizes interactively.
+
+## Running a pipeline with your current git changes
+
+`rwx run` sends a git patch with the run, so no commit or push is needed:
+
+- Base: the closest ancestor of local `HEAD` that is already on `origin`
+  (`event.git.sha` resolves to it).
+- Patch on top: unpushed commits, staged, unstaged, and untracked files.
+- Excluded: anything in `.gitignore`. Git LFS changes error out.
+- `RWX_DISABLE_GIT_PATCH=1` turns patching off.
+
+```bash
+rwx run .rwx/pyright.yml --wait                    # run, block, print results
+rwx run .rwx/pyright.yml --wait --fail-fast        # stop at first failure
+rwx run .rwx/pyright.yml --target <task-key> --wait  # one task plus its deps
+rwx run .rwx/pyright.yml --title "wip: my change" --json
+rwx run .rwx/pyright.yml --wait --init paths="app/foo.py app/bar.py"
+```
+
+Keep the `git/clone` task's `ref: ${{ init.commit-sha }}` and the `cli`
+trigger's `commit-sha: ${{ event.git.sha }}` when editing `.rwx/*.yml`. That
+wiring is what makes the patch apply.
+
+## Type checking without a local `.venv`
+
+Use `pyright.yml` / `pyrefly.yml` when there is no `.venv` or memory is tight.
+Both accept `paths` (space separated; empty means the whole project).
+
+```bash
+rwx run .rwx/pyright.yml --wait
+rwx run .rwx/pyrefly.yml --wait --init paths="app/foo.py"
+```
+
+## Results and logs ("CI failed")
+
+```bash
+rwx runs list
+rwx results <run-id>                        # status and failures; `rwx results -h` for branch/commit lookup
+rwx logs <task-id>                          # a failed run prints the failing task id
+rwx logs <run-id> --task <task-key> --output /tmp/logs
+rwx artifacts --help                        # download task artifacts
+rwx retry <run-id>                          # retry a run or task
+rwx cancel <run-id>
+```
+
+Use `--json` where available for parsing.
+
+## Sandboxes and debugging
+
+```bash
+rwx sandbox exec -- <command>   # run in a persistent RWX sandbox
+rwx debug <task-id>             # debug a task; `rwx ssh` attaches to a running one
+```
+
+## Writing or changing `.rwx/*.yml`
+
+1. Pull the reference docs and read them in full, untruncated:
+   `rwx docs pull /migrating/rwx-reference`.
+2. For anything else: `rwx docs search "<query>"`, then `rwx docs pull <path>`
+   (for example `/docs/cli-triggers`, `/docs/cli-reference/rwx-run`). Use
+   these instead of WebFetch.
+3. Validate after every edit: `rwx lint .rwx/<name>.yml`.
+4. Prefer packaged leaves over hand-rolled steps; `rwx lint` flags outdated
+   versions, and `rwx update` / `rwx resolve` bump or pin base images and
+   packages.
+5. Model tasks as a DAG: separate install from checks, and `filter:` install
+   tasks to lockfile inputs (see `pyright.yml`) so caching survives ordinary
+   commits. RWX caches by content, so drop GitHub-style cache steps.
+6. If you must download an installer, pin the version and verify its checksum,
+   as `pyright.yml` does for uv.
+
+## Migrating a GitHub Actions workflow
+
+Upstream skills: https://github.com/rwx-cloud/skills (`migrate-from-gha`,
+`review-gha-migration`). The approach: inventory jobs, `needs:`, secrets and
+env first, translate to a DAG using RWX packages, run `rwx lint`, then review
+the result against the inventory for dropped steps. Do not migrate the
+workflows that gate the merge queue without a request to do so.