chore: add CI, publish workflow, and issue/PR templates

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,99 @@
+name: 🐛 Bug report
+description: A component renders or behaves incorrectly.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file this. If you can, reproduce it in the
+        [playground](https://flowui.stac.dev/playground) first — it runs the
+        latest build, so it tells us quickly whether the bug is still there.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you saw, and where.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: |
+        The smallest widget tree that shows the problem — ideally something we
+        can drop into a fresh app and run. Include the steps if it only appears
+        after an interaction.
+      render: dart
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      options:
+        - FlowChatScreen
+        - FlowThread / FlowMessage
+        - FlowStreamingText
+        - FlowThinkingIndicator / FlowShimmerText
+        - FlowMessageActions
+        - FlowComposer
+        - FlowMenu / FlowModelSelector
+        - FlowAttachmentGroup / FlowAttachmentPreview
+        - FlowSuggestion / FlowSuggestionGroup
+        - FlowGreeting
+        - FlowTheme (colors, typography, dark mode)
+        - Playground app
+        - Something else / not sure
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: flow_ui version
+      description: The resolved version from your `pubspec.lock`, e.g. 0.2.0.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platforms
+    attributes:
+      label: Platforms
+      description: Where you see it. Pick every one you have checked.
+      multiple: true
+      options:
+        - Android
+        - iOS
+        - Web
+        - macOS
+        - Windows
+        - Linux
+    validations:
+      required: true
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots or recording
+      description: |
+        For anything visual — spacing, colour, animation, layout — this is the
+        fastest way to show us. Drag images in; they upload automatically.
+
+  - type: textarea
+    id: doctor
+    attributes:
+      label: flutter doctor -v
+      description: Paste the full output. It captures the Flutter and Dart versions we need.
+      render: text
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 📚 Documentation
+    url: https://flowui.stac.dev/
+    about: Component guides, theming, and the API surface.
+  - name: 🧩 Playground
+    url: https://flowui.stac.dev/playground
+    about: Reproduce it live against the latest build — every component has a stage with variant pills and code snippets.
+  - name: 🗺️ Roadmap
+    url: https://flowui.stac.dev/roadmap
+    about: Check whether the component you want is already planned.
+  - name: 🤓 API reference
+    url: https://pub.dev/documentation/flow_ui/latest/
+    about: Generated dartdoc for every public widget and token.

.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,26 @@
+name: 📚 Documentation
+description: Something on flowui.stac.dev, in the README, or in the API docs is wrong, unclear, or missing.
+labels: [documentation]
+body:
+  - type: input
+    id: where
+    attributes:
+      label: Where
+      description: The page URL, or the file if it's the README or a dartdoc comment.
+      placeholder: https://flowui.stac.dev/components/composer
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What's wrong
+      description: What the docs say (or don't say), and what tripped you up.
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: What would help
+      description: The correction, the missing example, or the section you expected to find.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,55 @@
+name: ✨ Feature or component request
+description: A new component, a variant, or an API that isn't there yet.
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Check the [roadmap](https://flowui.stac.dev/roadmap) first — several
+        components are already planned, and a 👍 on an existing issue helps us
+        order them.
+
+        Two constraints shape what can land here, so it's worth knowing them
+        before you write:
+
+        - **No third-party dependencies.** The package depends on the Flutter
+          SDK and Flutter's own first-party packages, nothing else.
+        - **Nothing model-facing.** Components render state passed in and report
+          intent through callbacks — no prompts, schemas, or provider calls.
+
+  - type: dropdown
+    id: kind
+    attributes:
+      label: What kind of request is this
+      options:
+        - A new component
+        - A variant or option on an existing component
+        - A new API, callback, or parameter
+        - A theming or design-token change
+        - Something else
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to build, and where does flow_ui get in the way today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you'd like
+      description: |
+        Sketch the API or the behaviour. Dart, a screenshot of the interface you
+        have in mind, or a link to a design all work.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you're doing instead
+      description: Workarounds you've tried, or how other libraries handle it.

.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- What changes, and why. Link the issue it closes: Closes #123 -->
+
+## Screenshots
+
+<!-- flow_ui is a UI library, so anything visual needs a picture. Delete this
+     section only if the change renders nothing. -->
+
+| Before | After |
+| --- | --- |
+|  |  |
+
+## How this was verified
+
+<!-- Which playground stages you exercised, on which platforms (and both
+     themes, if the change touches colour). -->
+
+## Checklist
+
+- [ ] `flutter analyze lib` and `flutter analyze` in `example/` and `playground/` are clean
+- [ ] `dart format .` applied
+- [ ] Exercised in the playground — with a stage demo added or updated if this is a new component or variant
+- [ ] No new entries under `dependencies:` in `pubspec.yaml` (Flutter SDK and flutter.dev packages only)
+- [ ] Nothing model-facing — no prompts, schemas, or provider/network calls
+- [ ] New public API is exported from `lib/flow_ui.dart` and documented in `docs/` and the README table
+- [ ] `CHANGELOG.md` updated for user-facing changes, with breaking changes called out
+- [ ] PR title follows conventional commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`)

.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# A new push to the same ref supersedes the run already in flight.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  package:
+    name: Package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+          cache: true
+
+      - run: flutter pub get
+
+      - name: Format
+        run: dart format --output=none --set-exit-if-changed .
+
+      # Scoped to lib/: from the repo root the analyzer also walks into
+      # example/ and playground/, which resolve their own dependencies and
+      # are analysed in the `apps` job instead.
+      - name: Analyze
+        run: flutter analyze lib
+
+      # test/ is deliberately empty while the component surface is still being
+      # reshaped design-first; this runs the day the first test lands.
+      - name: Test
+        run: |
+          if find test -name '*_test.dart' 2>/dev/null | grep -q .; then
+            flutter test
+          else
+            echo "No tests yet — skipping."
+          fi
+
+      # Catches packaging mistakes (a stale .pubignore, a missing asset, a
+      # broken README link) before a release tag, not after.
+      - name: Publish dry run
+        run: flutter pub publish --dry-run
+
+  apps:
+    name: ${{ matrix.app }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        app: [example, playground]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+          cache: true
+
+      - run: flutter pub get
+        working-directory: ${{ matrix.app }}
+
+      - run: flutter analyze
+        working-directory: ${{ matrix.app }}
+
+  docs:
+    name: Docs site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # `build:site` compiles the playground to wasm before Astro builds, so
+      # this job needs both toolchains.
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+          cache: true
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - run: npm ci
+        working-directory: docs
+
+      # The same build the deploy runs: playground → public/playground, then
+      # the site. Keeps a broken playground from reaching flowui.stac.dev.
+      - run: npm run build:site
+        working-directory: docs

.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+# Publishes to pub.dev when a version tag is pushed, e.g.
+#
+#   git tag v0.2.0 && git push origin v0.2.0
+#
+# Authentication is OIDC — no token lives in this repo. It requires automated
+# publishing to be enabled once on pub.dev (flow_ui → Admin → Automated
+# publishing) for StacDev/flow_ui with the tag pattern `v{{version}}`.
+name: Publish
+
+on:
+  push:
+    tags: ['v[0-9]+.[0-9]+.[0-9]+*']
+
+jobs:
+  publish:
+    permissions:
+      id-token: write # Required to mint the OIDC token pub.dev verifies.
+    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1