ci: automate IntentCall pub.dev publishing

.github/workflows/pub_publish.yml

@@ -0,0 +1,47 @@
+name: Publish pub.dev package
+
+on:
+  push:
+    tags:
+      - 'intentcall_*-v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to preflight, for example intentcall_core-v0.1.1'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: pub-dev-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pub.dev
+    timeout-minutes: 30
+    env:
+      RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+          cache: true
+
+      - uses: dart-lang/setup-dart@v1
+
+      - name: Workspace dependencies
+        run: dart pub get
+
+      - name: Release preflight
+        run: dart run tool/intentcall/bin/intentcall.dart publish-tag --tag "$RELEASE_TAG" --skip-existing
+
+      - name: Publish package
+        if: github.event_name == 'push'
+        run: dart run tool/intentcall/bin/intentcall.dart publish-tag --tag "$RELEASE_TAG" --execute --skip-existing

.github/workflows/release-please.yml

@@ -0,0 +1,21 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Release Please
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

.release-please-manifest.json

@@ -0,0 +1,12 @@
+{
+  "packages/intentcall_schema": "0.1.0",
+  "packages/intentcall_core": "0.1.0",
+  "packages/intentcall_session": "0.1.0",
+  "packages/intentcall_mcp": "0.1.0",
+  "packages/intentcall_webmcp": "0.1.0",
+  "packages/intentcall_apple": "0.1.0",
+  "packages/intentcall_android": "0.1.0",
+  "packages/intentcall_codegen": "0.1.0",
+  "packages/intentcall_platform": "0.1.0",
+  "packages/intentcall_testing": "0.1.0"
+}

PUBLISHING.md

@@ -4,6 +4,55 @@ Status: `0.1.0` has been published to pub.dev for the `intentcall_*`
 package train. Use this runbook for future releases; keep the first-publish
 checks only as historical/diagnostic guidance.
 
+## Automatic release and publish flow
+
+IntentCall uses manifest-driven Release Please plus tag-triggered pub.dev
+publishing:
+
+1. Conventional commits land on `main`.
+2. `.github/workflows/release-please.yml` opens or updates one release PR from
+   `release-please-config.json` and `.release-please-manifest.json`.
+3. The Release Please config links every publishable `intentcall_*` component
+   into one package train, including `intentcall_session`, so versions remain
+   synchronized.
+4. Merging the release PR creates component tags such as
+   `intentcall_core-v0.1.1`.
+5. `.github/workflows/pub_publish.yml` runs for each `intentcall_*-v*` tag and
+   publishes the package named by that tag. The workflow is skip-existing safe,
+   so rerunning a tag does not republish an already visible package version.
+
+This mirrors the `mcp_flutter` release pattern: Release Please owns version and
+changelog generation, while the native repo publish script owns pub.dev
+preflight and publishing.
+
+## Required GitHub and pub.dev configuration
+
+- Add a repository secret named `RELEASE_PLEASE_TOKEN` with permission to create
+  releases and tags that trigger follow-up workflows. If Release Please falls
+  back to `GITHUB_TOKEN`, GitHub can suppress the downstream tag-triggered
+  publish workflow.
+- Create a GitHub Actions environment named `pub.dev`. Add required reviewers
+  there if release publishing should be gated.
+- On pub.dev, enable automated publishing for every existing package in the
+  train. Use repository `Arenukvern/intentcall`, environment `pub.dev`, and the
+  package-specific tag pattern:
+
+```text
+intentcall_schema-v{{version}}
+intentcall_core-v{{version}}
+intentcall_session-v{{version}}
+intentcall_mcp-v{{version}}
+intentcall_webmcp-v{{version}}
+intentcall_apple-v{{version}}
+intentcall_android-v{{version}}
+intentcall_codegen-v{{version}}
+intentcall_platform-v{{version}}
+intentcall_testing-v{{version}}
+```
+
+No long-lived pub.dev token is required in GitHub Actions. The publish workflow
+uses GitHub OIDC through `dart-lang/setup-dart`.
+
 ## Prerequisites
 
 - `dart pub` logged in (`dart pub token add https://pub.dev`)
@@ -16,7 +65,7 @@ checks only as historical/diagnostic guidance.
 1. `intentcall_schema`
 2. `intentcall_core`
 3. `intentcall_session`
-4. `intentcall_mcp`, `intentcall_webmcp`, `intentcall_gemma`, `intentcall_apple`, `intentcall_android`, `intentcall_codegen`
+4. `intentcall_mcp`, `intentcall_webmcp`, `intentcall_apple`, `intentcall_android`, `intentcall_codegen`
 5. `intentcall_platform` (Flutter plugin — may need `flutter pub publish`)
 6. `intentcall_testing`
 
@@ -32,11 +81,17 @@ just publish-preflight
 # Validate all packages (CI uses this)
 just publish-dry-run
 
+# Validate one package tag the way automated publishing does
+just publish-tag-dry-run intentcall_session-v0.1.0
+
 # Diagnostic only while release-critical files are dirty; still fails archive/content errors
 just publish-dry-run-ignore-warnings
 
 # After credentials are configured
 just publish-execute
+
+# CI normally runs this from .github/workflows/pub_publish.yml on tag push
+just publish-tag-execute intentcall_session-v0.1.0
 ```
 
 For a brand-new package name, treat `just publish-preflight-first` as the release desk:
@@ -54,6 +109,9 @@ For `intentcall_platform`, if `dart pub publish` fails on Flutter constraints, r
 cd packages/intentcall_platform && flutter pub publish --dry-run
 ```
 
+`intentcall_gemma` is an example-only workspace package and is marked
+`publish_to: none`; do not include it in the pub.dev release train.
+
 ## After publish (mcp_flutter cutover)
 
 Status: the initial `0.1.0` hosted cutover is complete in `mcp_flutter`.

docs/DX_FAQ.mdx

@@ -36,6 +36,27 @@ just publish-dry-run
 # equivalent to: dart run tool/intentcall/bin/intentcall.dart publish-all
 ```
 
+**Q: How are IntentCall packages released automatically?**
+
+Release Please opens a release PR from `release-please-config.json` and
+`.release-please-manifest.json`. The packages are linked as one synchronized
+`intentcall_*` train, so merging the release PR creates component tags such as
+`intentcall_core-v0.1.1`. Each tag triggers `.github/workflows/pub_publish.yml`,
+which publishes the package named by the tag through pub.dev automated
+publishing.
+
+**Q: How do I dry-run the package selected by a release tag?**
+
+```bash
+just publish-tag-dry-run intentcall_session-v0.1.0
+# equivalent to: dart run tool/intentcall/bin/intentcall.dart publish-tag --tag intentcall_session-v0.1.0 --skip-existing
+```
+
+Pub.dev automated publishing must be enabled for every package with tag pattern
+`<package>-v{{version}}` and GitHub Actions environment `pub.dev`. The release
+workflow should use `RELEASE_PLEASE_TOKEN`; using only `GITHUB_TOKEN` can create
+tags without triggering the downstream publish workflow.
+
 ---
 
 ## 🏭 Adding a dependency
@@ -273,7 +294,7 @@ make check-intentcall-integration
 1. `intentcall_schema`
 2. `intentcall_core`
 3. `intentcall_session`
-4. `intentcall_mcp`, `intentcall_webmcp`, `intentcall_gemma`, `intentcall_apple`, `intentcall_android`, `intentcall_codegen` (parallel)
+4. `intentcall_mcp`, `intentcall_webmcp`, `intentcall_apple`, `intentcall_android`, `intentcall_codegen` (parallel)
 5. `intentcall_platform`
 6. `intentcall_testing`
 
@@ -299,6 +320,9 @@ just publish-execute
 
 This repo uses [release-please](https://github.com/googleapis/release-please). Merge a release PR generated by release-please, then run the publish command above.
 
+`intentcall_gemma` stays in the workspace as an example-only adapter package. It
+is marked `publish_to: none` and is not part of the pub.dev release train.
+
 ---
 
 ## 🔗 Local sibling repo path overrides

justfile

@@ -33,6 +33,14 @@ publish-preflight-first:
 publish-execute:
     dart run tool/intentcall/bin/intentcall.dart publish-all --execute
 
+# Dry-run the package selected by a release tag, for example intentcall_core-v0.1.1
+publish-tag-dry-run tag:
+    dart run tool/intentcall/bin/intentcall.dart publish-tag --tag {{tag}} --skip-existing
+
+# Publish the package selected by a release tag (CI-only in normal release flow)
+publish-tag-execute tag:
+    dart run tool/intentcall/bin/intentcall.dart publish-tag --tag {{tag}} --execute --skip-existing
+
 # Check for local IntentCall path dependencies in publishable packages
 check-path-deps:
     dart run tool/intentcall/bin/intentcall.dart check-path-deps

packages/intentcall_gemma/CHANGELOG.md

@@ -4,3 +4,4 @@
 
 - First pre-release of the optional Gemma adapter for IntentCall experiments.
 - Includes function-registration plumbing over the shared IntentCall registry.
+- Marked as an example-only workspace package, not a pub.dev publish target.

packages/intentcall_gemma/README.md

@@ -3,4 +3,13 @@
 
 # intentcall_gemma
 
-Example-only `GemmaPublishAdapter` for on-device Gemma experiments (not product-wired).
+Example-only `GemmaPublishAdapter` for on-device Gemma experiments.
+
+This package is intentionally not published to pub.dev. It remains in the
+workspace as executable reference code for mapping IntentCall tool registrations
+into Gemma-style function definitions, but it is not a supported product adapter
+or part of the hosted IntentCall package train.
+
+Use it as a small implementation sketch when building a concrete on-device
+Gemma bridge. Product packages should copy the relevant adapter shape into their
+own runtime integration and own the model/runtime policy there.

packages/intentcall_gemma/pubspec.yaml

@@ -1,5 +1,6 @@
 name: intentcall_gemma
-description: PRE-RELEASE — Example Gemma publish adapter for intentcall (optional on-device bridge).
+publish_to: none
+description: Example-only Gemma adapter for IntentCall experiments; not published to pub.dev.
 version: 0.1.0
 license: MIT
 repository: https://github.com/Arenukvern/intentcall/tree/main/packages/intentcall_gemma

packages/intentcall_session/CHANGELOG.md

@@ -5,3 +5,5 @@
 - First pre-release of IntentCall runtime session persistence and invocation helpers.
 - Includes file-backed session state, state locking, safe writes, session lifecycle
   management, and an `AgentRegistry` session executor.
+- Documents the public session, invocation, and snapshot flow with a runnable
+  package example.

packages/intentcall_session/README.md

@@ -6,6 +6,7 @@ IntentCall runtime sessions for commandable tools and apps.
 
 Use this package when a CLI, MCP server, app host, or agent tool needs to keep a
 durable attachment to a live runtime before invoking IntentCall registry entries.
+See `example/session_example.dart` for a complete runnable in-memory example.
 
 This package owns reusable runtime persistence mechanics:
 
@@ -55,6 +56,11 @@ final result = await manager.startSession(
 );
 ```
 
+The connector is implemented by the host. A minimal connector only needs to
+resolve an endpoint display string and report any target-selection diagnostics.
+The package does not open sockets or know about Flutter, MCP, devices, browsers,
+or daemons by itself.
+
 ## Invoke through a session
 
 ```dart
@@ -96,6 +102,16 @@ Hosts own how snapshots are produced. For example, Flutter MCP has a command
 snapshot service that executes its command catalog and stores the resulting JSON
 through this package.
 
+## Run the example
+
+```bash
+dart run packages/intentcall_session/example/session_example.dart
+```
+
+The example creates a fake connector, starts a persisted session, invokes an
+`AgentRegistry` entry through that session, writes two JSON snapshots, and prints
+a structural diff.
+
 ## Boundaries
 
 `intentcall_session` is not a broker facade. A product broker can compose this